REPORTE DEMORA

Fuente: /var/www/html/qareportes/app/Http/Controllers/Cloud/ReportController.php

1) Nombre del reporte

Nombre: Reporte Demora
Código / Alias: report_demora
Responsable: Equipo de Reportes Cloud
Propósito (1 línea):

2) Alcance temporal

Campo(s) de fecha utilizados:

first_date → Primer día del mes
second_date → Último día del mes
created_date → Fecha y Hora de creación

Tipo de rango (diario / mensual / personalizado): Personalizado(entre first_date y second_date)
Inclusión de horas (sí/no). Si sí: [00:00:00 – 23:59:59]
Zona horaria: La del servidor

3) Origen de datos (tablas/APIs)

3.1 Conexión / Base: Empresarial

Tabla / Recurso: emp_terminal
Alias (si aplica): no aplica
Campos utilizados (clave → descripción):

ter_nombre → Nombre de terminal
ter_id → ID de la terminal
ter_habilitado →Estado de la terminal (1 = habilitado, 0 = deshabilitado )

Condiciones (WHERE) aplicadas: No aplica
Tipo de unión con otras fuentes (JOIN y llave): No aplica
Observaciones (ej. particiones, índices): Sin obs

3.2 Conexión / Base: Shalom choferes

Tabla / Recurso: emp_demora
Alias (si aplica): no aplica
Campos utilizados (clave → descripción):

cap_id → Identificador Carguero Programado
monto → Motivo (select)
subtipo → Depende del tipo de Motivo (también es un select)
observacion → Descripcion del Motivo/subtipo
fecha → Fecha de registro
user → Usuario que realiza el registro
terminal_responsable → Terminal responsable
fh_inicio_demora → Fecha y hora en que se registró la demora
fh_fin_demora → Fecha y hora en que se finalizó la demora
terminal_salida → ID de la terminal Origen
terminal_llegada → D de la terminal Destino
estado_incidencia → 1 = VÁLIDO / 0 = IVALIDO

Condiciones (WHERE) aplicadas:

Filtra registro con estado = 1
Filtra registros con fechas que están entre first_date y second_date

Tipo de unión con otras fuentes (JOIN y llave): No aplica
Observaciones (ej. particiones, índices): Sin obs

3.3 Conexión / Base: Empresarial

Tabla / Recurso: emp_cargprogramado
Alias (si aplica): no aplica
Campos utilizados (clave → descripción):

cap_id → Identificador de carguero programado
cap_rutacarguero → Ruta de carguero
cap_cargueroid → Identificador de carguero

Condiciones (WHERE) aplicadas: Filtra registros de la tabla emp_cargprogramado si encuentra coincidencias en cap_id con los registros de la tabla emp_demora.
Tipo de unión con otras fuentes (JOIN y llave): No aplica
Observaciones (ej. particiones, índices): Sin obs

3.4 Conexión / Base: Empresarial

Tabla / Recurso: emp_persona
Alias (si aplica): no aplica
Campos utilizados (clave → descripción):

per_nrodocumento
per_nombrerzsoc
per_apellidopaterno
per_apellidomaterno

Condiciones (WHERE) aplicadas: Filtra los registros de la tabla emp_persona que coincidan en documento de identidad con el usuario que registró la demora (per_nrodocumento == user)

Tipo de unión con otras fuentes (JOIN y llave): No aplica
Observaciones (ej. particiones, índices): Sin obs

4) Filtros globales del reporte

Inclusiones (must-have): Sólo se incluyen demoras activas (estado = 1) y dentro del rango de fechas indicado.
Exclusiones (reglas de descarte):

Todo lo que no cumpla estado = 1 queda automáticamente descartado.
Todo lo que esté fuera del rango de fechas (first_date, second_date) también se descarta.

Reglas por estado / habilitado:

En la tabla de emp_demora se procesan registros con estado = 1
En la tabla de emp_terminal se procesan registros con estado = 1

Parámetros externos (si el usuario puede filtrarlo): first_date y second_date son parámetros externos que se pueden definir por el usuario que definen el rango de fecha

5) Transformaciones y Reglas de negocio

Derivaciones de campos (cómo se calculan):

$db → "report_demora_" . date("Y_m", strtotime($demora->fecha));
$fehca → date("Y-m-d", strtotime($demora->fecha));
placa → id_carguero - Proviene de un json de la tabla emp_cargprogramado
ruta → cap_rutacarguero - Proviene de un json de la tabla emp_cargprogramado

Mapeos de estado:

estado_incidencia → por defecto “PENDIENTE”

1 == “VALIDO”
2 == “INVALIDO”

Reglas de validación (p.ej., sólo registros validados):

Solo se procesan registros con estado habilitado de la tabla emp_demora
Solo se procesan registros con estado habilitado de la tabla emp_embarque_aereo

Reglas condicionales (si X entonces Y):

Si el motivo de la demora es "Demora De Terminales" se guarda la terminal de salida, caso contrario es null.

Si el motivo de la demora es "Demora De Terminales" se guarda la terminal de llegada, caso contrario es null.

6) Estructura de salida

Tabla/archivo destino: report_demora
Particionado / sufijo: El particionado se hace por mes y año usando sufijo YYYY_MM. ( ejm: report_demora_2025_09)
Clave(s) primaria(s) o únicas:
Columnas del reporte (nombre → tipo → descripción):

id→INT (PK) → Identificador único autoincremental
fecha_incidencia→DATE→Fecha de la demora
placa→VARCHAR(20)→Identificador del vehículo/carguero
ruta→VARCHAR(100)→Ruta asignada
tipo_de_demora→VARCHAR(50)→Categoría de demora (monto)
incidencia→VARCHAR(100)→Subtipo de la demora
agencia_involucrada→VARCHAR(70)→Nombre del terminal responsable
observacion→TEXT→Observaciones registradas
nombre_usuario→VARCHAR(100)→Usuario asociado
terminal_salida→VARCHAR(100)→Terminal de salida (si aplica)
terminal_llegada→VARCHAR(100)→Terminal de llegada (si aplica)
estado→VARCHAR(10)→Estado transformado (PENDIENTE, VALIDO, INVALIDO)
created_date→DATETIME→Fecha y hora de creación del registro en la tabla
status→tinyint(4)→Estado de habilitación (1 = activo)

Ordenamiento por defecto: No se especifica ORDER BY

7) Frecuencia y operación

Frecuencia de actualización: Se ejecuta desde el método updateReportDemora().
Ventana que recalcula (días/meses): Se realiza mensualmente tomando los parámetros first_month y last_month (primer y último día del mes).
Tamaño de lote / paginado (chunking):

Se insertan máximo 900 registros por batch
Se consulta emp_cargprogramado en lotes de 1000 IDs

Tolerancia a fallos / reintentos:

Si no se puede crear/verificar la tabla:

Inserta un registro en error_reports para auditar el fallo.
Usa continue; para no detener todo el proceso.

En updateReportDemora también:

Si ocurre un error, registra en emp_reportes_validation con status = 0.
No hay reintento automático inmediato, pero sí un log de fallos.

Tiempos de ejecución esperados: Tiempo esperado depende de cantidad de demoras procesadas

8) Calidad y controles

Validaciones previas/post:

Antes de insertar datos en las tablas dinámicas (report_demora_YYYY_MM), se valida si la tabla existe, si no existe se crea.

Controles de duplicados: no se encontró
Métricas de completitud (qué se monitorea): Se inserta en emp_reportes_validation el rango procesado junto al status (1 = ok, 0 = error). Eso funciona como log de validación de ejecución.

9) Dependencias externas

APIs / servicios y endpoints:

emp_terminal
emp_demora
emp_cargprogramado
emp_persona

Autenticación / headers: no aplica
Mapeos y contratos de datos:

cap_id → se busca en emp_cargprogramado para obtener cap_cargueroid y cap_rutacarguero.

user → se mapea a per_nrodocumento en emp_persona.

terminal_responsable, terminal_salida, terminal_llegada → se mapean a nombres de terminales ($jsonTerms).

estado_incidencia → se transforma de numérico (1, 2) a texto (VALIDO, INVALIDO).

10) Historial de cambios

2025-09-18 18:22 - Elian Franco Arroyo Rodas - Documentación inicial