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