REPORTE AMOUNT PLATAFORMAS

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

1) Nombre del reporte

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

2) Alcance temporal

Campo(s) de fecha utilizados:

ose_fhpreferenciapartida
cop_fechaemision
created_date
fecha_consult
fecha

Tipo de rango (diario / mensual / personalizado): Mensual, con generación por días dentro del rango (generateArrayOfDays) y posible extensión al último mes del año anterior (si el mes actual es enero o febrero).
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: Empresarial

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

ose_id → Identificador de la orden de servicio.
ose_termorigenatencion → Terminal de origen de la orden.
ose_termdestinoentrega → Terminal de destino de la orden.
ose_fhpreferenciapartida → Fecha de preferencia de partida.
ose_estado → Estado de la orden (1 = activo, otros valores indican cancelado o inactivo).
ose_estadoPago → Estado del pago (AN = anulado, DA = dado de baja).
ose_tipoanulado → Tipo de anulación, vacío si está vigente.
eliminado → Indicador lógico de eliminación.

Condiciones (WHERE) aplicadas:

Filtra las órdenes de servicio activas y vigentes dentro del rango de fechas ($fecha 00:00:00 hasta $fecha 23:59:59), excluyendo las anuladas o dadas de baja. Solo se consideran registros no eliminados.

Tipo de unión con otras fuentes (JOIN y llave): LEFT JOIN con emp_entrega (campo llave: ent.ent_osid = os.ose_id).
Observaciones (ej. particiones, índices): La tabla emp_ordenservicio suele tener índices por campos ose_id, ose_fhpreferenciapartida, y ose_estado para optimizar las consultas de rango y estado.

3.2 Conexión / Base: Empresarial

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

ent_id → Identificador del registro de entrega.
ent_persona → Documento o ID de la persona asociada a la entrega.
ent_osid → Identificador de la orden de servicio vinculada.
ent_eliminado → Indicador de eliminación lógica.

Condiciones (WHERE) aplicadas:

Se filtran entregas no eliminadas (ent_eliminado = 0) asociadas a personas específicas (lista de DNI o IDs) dentro del rango de fechas.

Tipo de unión con otras fuentes (JOIN y llave): LEFT JOIN con emp_ordenservicio (llave: ent.ent_osid = os.ose_id).
Observaciones (ej. particiones, índices): Campos ent_id y ent_osid comúnmente indexados.

3.3 Conexión / Base: Empresarial

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

ter_id → Identificador de la terminal.
ter_nombre → Nombre descriptivo de la terminal.
ter_zona → Zona geográfica o grupo operativo.

Condiciones (WHERE) aplicadas:

No aplica filtrado. Se obtiene el listado completo de terminales activas registradas en la base de datos.

Tipo de unión con otras fuentes (JOIN y llave): No aplica unión, solo lectura directa.
Observaciones (ej. particiones, índices): Posible índice sobre ter_id (PK) y ter_zona para agrupación posterior.

3.4 Conexión / Base: Empresarial

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

id → Identificador del detalle.
dcp_ose_id → Identificador de la orden de servicio relacionada.
dcp_cop_id → Identificador del comprobante de pago vinculado.

Condiciones (WHERE) aplicadas:

Obtiene registros de detalle que pertenecen a órdenes de servicio procesadas (whereIn(dcp_ose_id, $groups)), agrupando los comprobantes vinculados a cada orden.

Tipo de unión con otras fuentes (JOIN y llave): No aplica JOIN explícito, pero se vincula lógicamente con emp_comppago mediante dcp_cop_id.
Observaciones (ej. particiones, índices): Índices comunes en dcp_ose_id y dcp_cop_id para relaciones y búsquedas cruzadas.

3.5 Conexión / Base: Empresarial

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

cop_id → Identificador del comprobante de pago.
cop_fechaemision → Fecha de emisión del comprobante.
cop_terminal → Terminal de origen.
cop_estado_pago → Estado del pago (nulo o diferente de “AN” indica activo).
cop_tipo → Tipo de comprobante (solo se consideran los de tipo “NC” → Nota de Crédito).

Condiciones (WHERE) aplicadas:

Selecciona comprobantes tipo “NC” emitidos en el rango horario del día (00:00:00 a 23:59:59) y que no estén anulados (cop_estado_pago nulo o distinto de “AN”).

Tipo de unión con otras fuentes (JOIN y llave): Relación lógica con emp_detalle_comppago (llave: dcp_cop_id = cop_id).
Observaciones (ej. particiones, índices): Índices esperados en cop_id, cop_fechaemision y cop_estado_pago por alto volumen de registros.

3.6 Conexión / Base: Empresarial

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

osd_id → Identificador del detalle.
osd_osid → Identificador de la orden de servicio.
osd_descripcion → Código de tipo de paquete (3 = sobre, 1096 = xxs, 1090 = xs, 5 = s, 1093 = m, 2 = l).
osd_unidad → Cantidad de unidades.
osd_montototal → Monto total del detalle.
osd_eliminado → Indicador lógico de eliminación.

Condiciones (WHERE) aplicadas:

Filtra los detalles activos (osd_eliminado = 0) y solo de los tipos válidos de paquete definidos en el array de referencia.

Tipo de unión con otras fuentes (JOIN y llave): Vinculación lógica con emp_ordenservicio a través de osd_osid = ose_id.
Observaciones (ej. particiones, índices): Campos osd_osid y osd_descripcion con índice para mejorar rendimiento en consultas por tipo.

4) Filtros globales del reporte

Inclusiones (must-have):

Órdenes activas y no anuladas.
Comprobantes válidos (no anulados).
Terminales habilitadas.

Exclusiones (reglas de descarte):

Órdenes anuladas o con estado de pago “AN” o “DA”.
Entregas eliminadas.

Reglas por estado / habilitado: Solo se consideran órdenes con ose_estado = 1.
Parámetros externos (si el usuario puede filtrarlo):

Año y mes dinámico ($year, $last_month, $first_month)
Fechas de inicio y fin generadas automáticamente.

5) Transformaciones y Reglas de negocio

Derivaciones de campos (cómo se calculan):

paquete_*, sobre, efectivo, banco, billetera_electronica → acumulados por tipo y terminal.
type = “envia_ya” o “pro” según rcontacto.
Totales diarios por origen y destino.

Mapeos de estado:

ose_servpagotipo = 1 → efectivo
ose_servpagotipo = 2 → contra_entrega
cop_tipopago = QR → billetera_electronica
cop_tipopago = BANCO → banco

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

Reglas condicionales (si X entonces Y):

Ignora órdenes donde ose_remitecontactomail != 1.
Incluye datos del año anterior si mes actual ≤ 2.

6) Estructura de salida

Tabla/archivo destino: report_monto_plataformas_YYYY_MM
Particionado / sufijo: Mensual (YYYY_MM)
Clave(s) primaria(s) o únicas: id (auto-increment)
Columnas del reporte (nombre → tipo → descripción):

fecha → DATE → Día del registro
agencia_id → VARCHAR(100) → Identificador de la agencia
agencia → VARCHAR(255) → Nombre de la agencia
plataforma → VARCHAR(255) → Tipo de plataforma utilizada (“envia_ya”, “pro”)
cantidad_origen → VARCHAR(10) → Cantidad enviada desde el punto de origen
cantidad_destino → VARCHAR(10) → Cantidad recibida en el punto de destino
monto_origen → VARCHAR(10) → Monto total emitido desde origen
monto_destino → VARCHAR(10) → Monto total recibido en destino
sobre / paquete_* → VARCHAR(10) → Cantidades agrupadas según tipo de paquete (sobre, paquete, etc.)
efectivo → VARCHAR(10) → Total de operaciones pagadas en efectivo
banco → VARCHAR(10) → Total de operaciones con pago bancario
billetera_electronica → VARCHAR(10) → Total de pagos mediante billetera electrónica
contra_entrega → VARCHAR(10) → Total de operaciones con modalidad contra entrega
created_date → DATETIME → Fecha de creación del registro
status → TINYINT(1) → Estado del registro (1 = activo / 0 = inactivo)

Ordenamiento por defecto: fecha ASC, agencia_id ASC

7) Frecuencia y operación

Frecuencia de actualización: PENDIENTE (Esperando info de Eduardo)
Ventana que recalcula (días/meses): Mensual, ejecutado automáticamente por rango de fechas.
Tamaño de lote / paginado (chunking): Inserciones en bloques de 900 registros (array_chunk).
Tolerancia a fallos / reintentos: Manejo con try/catch y rollback en errores.
Tiempos de ejecución esperados: PENDIENTE (Esperando info de Eduardo)

8) Calidad y controles

Validaciones previas/post: Verificación de existencia de tabla (verifyExistTable), creación o truncado según corresponda.
Controles de duplicados: Se ejecuta truncate si la tabla ya existe antes de insertar datos nuevos.
Métricas de completitud (qué se monitorea):

Creación exitosa de tabla mensual.
Estado en emp_reportes_validation.status (1=ok, 0=error).

9) Dependencias externas

APIs / servicios y endpoints: No aplica (todo interno a BD).
Autenticación / headers: No aplica.
Mapeos y contratos de datos: Uso interno de modelos $this->empresarial, $this->reportes, $this->centos.

10) Historial de cambios

2025-10-17 17:49 - Elian Franco Arroyo Rodas - Documentación inicial