REPORTE INFORMATION

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

1) Nombre del reporte

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

2) Alcance temporal

Campo(s) de fecha utilizados:

ose_fhpreferenciapartida (Guías emitidas)
ent_fecha (Entregas)
cop_fechaemision (Comprobantes emitidos)
cop_fhanulado (Comprobantes anulados)
ose_fechaanulado (GRT anuladas)

Tipo de rango (diario / mensual / personalizado): con subdivisión diaria dentro del mes. Se generan intervalos desde first_month hasta last_month del año actual, extendiéndose a diciembre del año anterior si el mes actual ≤ 2.
Inclusión de horas (sí/no). Si [00:00:00 – 23:59:59]
Zona horaria: La del servidor

3) Origen de datos (tablas/APIs)

3.1 Conexión / Base: CAPACITACION

Tabla / Recurso: tabEmployee
Alias (si aplica): No aplica

Campos utilizados (clave → descripción):

name → Identificador del empleado
nombre_completo → Nombre completo del empleado
passport_number → Número de documento (usado como clave con usuario)

Condiciones (WHERE) aplicadas: Obtiene todos los registros de empleados, ordenados alfabéticamente por nombre.

Tipo de unión con otras fuentes (JOIN y llave): Relación lógica con usuarios (emp_usuario.usr_id = passport_number).
Observaciones (ej. particiones, índices): Fuente API externa consumida vía método dbErp() hacia APICAPACITACION/method/send-query-database.

3.2 Conexión / Base: EMPRESARIAL

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

usr_id → Identificador del usuario
usr_terminalid → ID de la terminal asignada
usr_alias → Nombre o alias de usuario
usr_rol → Rol del usuario

Condiciones (WHERE) aplicadas: No aplica filtros, obtiene todos los usuarios activos.

Tipo de unión con otras fuentes (JOIN y llave): Llave lógica con emp_persona.per_nrodocumento = emp_usuario.usr_id.
Observaciones (ej. particiones, índices): No presenta filtros de estado ni eliminación, posible optimización agregando WHERE usr_estado = 1.

3.3 Conexión / Base: EMPRESARIAL

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

per_nrodocumento → Documento de identidad (clave)
per_nombrerzsoc, per_apellidopaterno, per_apellidomaterno → Concatenados como nombre completo

Condiciones (WHERE) aplicadas: Filtra personas cuyo documento (per_nrodocumento) exista en el conjunto de usuarios (usr_id).

Tipo de unión con otras fuentes (JOIN y llave): INNER JOIN lógico por documento.
Observaciones (ej. particiones, índices): Usado solo si no se encuentra coincidencia en la tabla de empleados.

3.4 Conexión / Base: EMPRESARIAL

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

ter_id → Identificador de terminal
ter_nombre → Nombre de terminal
ter_zona → Zona asignada

Condiciones (WHERE) aplicadas: No aplica. Se obtiene toda la lista de terminales.

Tipo de unión con otras fuentes (JOIN y llave): LEFT JOIN lógico mediante usr_terminalid.
Observaciones (ej. particiones, índices): Usado para mostrar el nombre de la terminal asociada al usuario.

3.5 Conexión / Base: EMPRESARIAL

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

ose_id → Identificador de orden
ose_fhpreferenciapartida → Fecha preferida de partida
ose_montototal → Monto total de la orden
usercreaid → Usuario que generó la orden
ose_estadoPago, ose_tipoanulado, ose_estado, eliminado → Estados de control

Condiciones (WHERE) aplicadas:

Se filtran las órdenes con:

Estado pago distinto de AN o DA
ose_tipoanulado vacío
ose_estado = '1' y eliminado = '0'
Rango de fechas (ose_fhpreferenciapartida BETWEEN fecha_inicio AND fecha_fin)
usercreaid perteneciente al grupo de usuarios válidos.

Tipo de unión con otras fuentes (JOIN y llave): No aplica (consulta directa).
Observaciones (ej. particiones, índices): Los resultados se agrupan por fecha y usuario.

3.6 Conexión / Base: EMPRESARIAL

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

ent_user → Usuario que registra la entrega
ent_fecha → Fecha de entrega
ent_eliminado → Indicador lógico de borrado
ent_osid → Clave foránea hacia emp_ordenservicio

Condiciones (WHERE) aplicadas:

ose_estadoPago NOT IN ('DA', 'AN')
ose_tipoanulado vacío
os.eliminado = '0' y os.ose_estado = '1'
ent.ent_eliminado = '0'
Rango de fechas (ent_fecha BETWEEN inicio y fin)
ent_user dentro de los usuarios válidos.

Tipo de unión con otras fuentes (JOIN y llave): LEFT JOIN emp_ordenservicio os ON ent.ent_osid = os.ose_id
Observaciones (ej. particiones, índices): Agrupa por fecha y usuario.

3.7 Conexión / Base: EMPRESARIAL

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

cop_id → Identificador de comprobante
cop_montoTotal → Monto total
cop_fechaemision → Fecha de emisión
cop_estado_pago → Estado del comprobante
usercreaid → Usuario que generó el comprobante

Condiciones (WHERE) aplicadas:

cop_estado_pago != 'AN'
cop_estado = '1'
eliminado = '0'
Rango de fechas (cop_fechaemision BETWEEN inicio y fin)
Usuario en lista válida.

Tipo de unión con otras fuentes (JOIN y llave): no aplica
Observaciones (ej. particiones, índices): Agrupado por fecha y usuario.

3.8 Conexión / Base: EMPRESARIAL

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

cop_id
cop_fhanulado
cop_estado_pago
useranula
cop_nota_credito

Condiciones (WHERE) aplicadas:

cop_estado_pago = 'AN'
cop_nota_credito IS NULL OR cop_nota_credito != '1'
cop_fhanulado BETWEEN inicio y fin
useranula dentro del grupo de usuarios válidos.

Tipo de unión con otras fuentes (JOIN y llave): no aplica
Observaciones (ej. particiones, índices): Se obtienen comprobantes anulados, agrupados por fecha y usuario.

3.8 Conexión / Base: EMPRESARIAL

Tabla / Recurso: emp_ordenservicio (GRT anuladas)
Alias (si aplica): os
Campos utilizados (clave → descripción):

ose_id
ose_fechaanulado
ose_estadoPago
ose_personaanulado
ose_remitecontactofono

Condiciones (WHERE) aplicadas:

ose_estadoPago = 'AN'
ose_fechaanulado dentro del rango de fechas
ose_personaanulado en la lista de usuarios válidos
ose_remitecontactofono nulo o distinto de ['WEB', 'REGISTRA', 'CLIENTES']

Tipo de unión con otras fuentes (JOIN y llave): no aplica
Observaciones (ej. particiones, índices): Filtra GRT anuladas sin remitentes especiales.

4) Filtros globales del reporte

Inclusiones (must-have):

Usuarios activos (ose_estado = '1', cop_estado = '1')
Registros no eliminados (eliminado = '0')

Exclusiones (reglas de descarte): Comprobantes o guías anuladas (estadoPago IN ('AN','DA'))
Reglas por estado / habilitado: Solo documentos vigentes y operativos.
Parámetros externos (si el usuario puede filtrarlo): Año y rango de meses se calculan automáticamente; no son ingresados manualmente.

5) Transformaciones y Reglas de negocio

Derivaciones de campos (cómo se calculan):

Se consolida información diaria por usuario, terminal y fecha.
Cálculos: cantidad, monto sumados por tipo (GRT, comprobantes, entregas, anulaciones).

Mapeos de estado:

usr_id ↔ passport_number ↔ per_nrodocumento
Terminales por usr_terminalid

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

Evita inserción de tablas vacías.
Control de existencia de tabla base antes de crear o reemplazar.

Reglas condicionales (si X entonces Y):

Si el mes ≤ 2, también incluye diciembre del año anterior.
Si una tabla mensual no existe, se crea clonando report_information.

6) Estructura de salida

Tabla/archivo destino: report_information_YYYY_MM
Particionado / sufijo: Mensual (sufijo año_mes).
Clave(s) primaria(s) o únicas: (fecha, usuario)
Columnas del reporte (nombre → tipo → descripción):

fecha → DATE → Día del registro
terminal_id → INT(5) → Identificador del terminal
terminal → VARCHAR(150) → Nombre del terminal
usuario → VARCHAR(13) → Identificador del usuario
usuario_nombre → VARCHAR(80) → Nombre completo del usuario
usuario_rol → VARCHAR(80) → Rol asignado al usuario
grt_emitidas_cantidad → INT → Total de guías emitidas
grt_emitidas_monto → DOUBLE(12,2) → Monto total de guías emitidas
grt_entregadas_cantidad → INT → Total de entregas realizadas
grt_entregadas_monto → DOUBLE(12,2) → Monto total de entregas realizadas
comprobantes_emitidos_cantidad → INT → Total de comprobantes emitidos
comprobantes_emitidos_monto → DOUBLE(12,2) → Monto total de comprobantes emitidos
grt_anuladas_cantidad → INT → Total de guías anuladas
comprobantes_anuladas_cantidad → INT → Total de comprobantes anulados
created_date → DATETIME → Fecha de inserción del registro
status → TINYINT → Estado del registro (1 = activo / 0 = inactivo)

Ordenamiento por defecto: fecha ASC, usuario ASC

7) Frecuencia y operación

Frecuencia de actualización: PENDIENTE (Esperando info de Eduardo)
Ventana que recalcula (días/meses): 2 meses anteriores si aplica.
Tamaño de lote / paginado (chunking): Inserciones por lotes de 300 registros.
Tolerancia a fallos / reintentos:

Reintentos hasta 4 veces para RENAME TABLE.
Fallback DELETE+INSERT si el swap falla.

Tiempos de ejecución esperados: PENDIENTE (Esperando info de Eduardo)

8) Calidad y controles

Validaciones previas/post:

Confirmación de existencia de tabla base.
Log de errores en error_reports.

Controles de duplicados: Reemplazo controlado (safeReplaceMonthlyTable) evita duplicados.
Métricas de completitud (qué se monitorea):

Conteo de registros insertados y estado de validación (emp_reportes_validation).

9) Dependencias externas

APIs / servicios y endpoints: APICAPACITACION/method/send-query-database
Autenticación / headers: JSON Headers (Accept, Content-Type)
Mapeos y contratos de datos:

Servicios Internos: $this->reports, $this->empresarial, $this->centos (conexiones BD internas)
Contratos: Formato JSON con campos valor, response, msn.

10) Historial de cambios

2025-10-15 12:46 - Elian Franco Arroyo Rodas - Documentación inicial