REPORTE SHIPPING AMOUNT PARTTOW

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

1) Nombre del reporte

• Nombre: Reporte Shipping Amount PartTwo

• Código / Alias:  report_shipping_amount_part_two_

• Responsable:  Equipo de Reportes Cloud

• Propósito (1 línea):

2) Alcance temporal

• Campo(s) de fecha utilizados:

• fecha en emp_cierre_aereo

• cop_fechaemision en emp_comppago_dhl

• ose_fhpreferenciapartida, ose_fhpreferencial en emp_ordenservicio
  
  

• Tipo de rango (diario / mensual / personalizado):  

• Personalizado (desde $first_date hasta $second_date)

• Se generan registros diarios (range con DatePeriod → iteración día a día).

• Inclusión de horas (sí/no).: Sí  [00:00:00 – 23:59:59]

• Zona horaria: La del servidor 

3) Origen de datos (tablas/APIs)

3.1 Conexión / Base: CENTOS

• Tabla / Recurso: emp_cierre_aereo

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• id → Identificador del cierre aéreo

• cap_id → Código de capacidad o identificador del cierre

• general → Kilaje general del cierre

• peligrosa → Kilaje de carga peligrosa

• valiosa → Kilaje de carga valiosa

• detalle_mercaderia → Detalle del contenido transportado (JSON)

• fecha → Fecha del registro del cierre aéreo

• Condiciones (WHERE) aplicadas:

• Se filtran los registros donde el campo estado sea igual a 1 (cerrados activos) y cuya fecha esté dentro del rango definido por las variables $finit y $ffend, es decir, entre la fecha de inicio y fin del reporte.

 

• Tipo de unión con otras fuentes (JOIN y llave): Relaciona mediante id con cierre_id de la tabla emp_embarque_aereo.

• Observaciones (ej. particiones, índices): 

• Tabla utilizada para obtener cierres aéreos con detalle de mercadería, se decodifica su campo JSON para cálculo de kilaje.

3.2 Conexión / Base: CENTOS

• Tabla / Recurso: emp_embarque_aereo

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• id → Identificador del embarque aéreo

• ose_id → Identificador del orden de servicio relacionada

• terminal → Terminal donde se realizó el embarque

• fecha → Fecha del embarque

• cierre_id → Identificador del cierre aéreo asociado

• Condiciones (WHERE) aplicadas:

• Se seleccionan los registros cuyo cierre_id exista dentro del conjunto de cierres aéreos previamente filtrados (array_keys($cierres_aereos_json)).

 

• Tipo de unión con otras fuentes (JOIN y llave): Une con emp_cierre_aereo (por cierre_id) y con emp_ordenservicio (por ose_id).

• Observaciones (ej. particiones, índices): 

• El resultado se agrupa por ose_id para obtener un resumen por orden de servicio.
  
  

3.3 Conexión / Base: EMPRESARIAL

• Tabla / Recurso: emp_ordenservicio

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• ose_id → Identificador de orden de servicio

• ose_fhpreferenciapartida → Fecha preferencial de partida

• ose_fhpreferencial → Fecha alternativa de programación

• ose_termorigenatencion → Terminal de origen

• ose_termdestinoentrega → Terminal de destino

• ose_estadoPago → Estado del pago de la orden

• ose_tipoanulado → Indicador de anulación

• ose_remiteempresa → Empresa remitente

• ose_destinaempresa → Empresa destinataria

• ose_montofinal → Monto total del servicio

• ose_estadoentregado → Estado de entrega del servicio

• ose_remitecontactofono → Contacto de remitente

• ose_remitecontactomail → Correo del remitente

• ose_observacion_cambioprecio → Tipo de orden de servicio

• Condiciones (WHERE) aplicadas:

• Filtra órdenes de servicio activas (ose_estado = 1) y no eliminadas (eliminado = 0), excluye aquellas con estados de pago “AN” (Anulado) o “DA” (Dado de baja), y valida que no tengan tipo de anulación (ose_tipoanulado vacío).

• Además, restringe por rango de fecha (ose_fhpreferenciapartida o ose_fhpreferencial entre $finit y $ffend), y si la variable $terminal está definida, se filtran registros cuyo origen o destino coincidan con esa terminal.

 

• Tipo de unión con otras fuentes (JOIN y llave): Relaciona con emp_embarque_aereo mediante ose_id, y con emp_envio_aereo, emp_incidencias, emp_adicionales y emp_empresa en distintas etapas del procesamiento.

• Observaciones (ej. particiones, índices): 

• Es la tabla base para la mayoría de cálculos de métricas (corporativo, comercial, reparto, etc.).

3.4 Conexión / Base: EMPRESARIAL

• Tabla / Recurso: emp_comppago_dhl

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• numero_dhl → Número de comprobante DHL

• cop_id → Identificador del comprobante

• cop_terminal → Terminal del comprobante

• cop_montoTotal → Monto total del comprobante

• cop_fechaemision → Fecha de emisión del comprobante

• Condiciones (WHERE) aplicadas:

• Solo se consideran los comprobantes con cop_estado_pago distinto de “AN” (no anulados), cop_estado = 1 (activos) y eliminado = 0.

 

• Tipo de unión con otras fuentes (JOIN y llave): No aplica unión directa; los datos se agregan por terminal y fecha para análisis comparativo.

• Observaciones (ej. particiones, índices): 

• Los montos y cantidades se agrupan manualmente por terminal y día.

3.5 Conexión / Base: EMPRESARIAL

• Tabla / Recurso:  emp_terminal

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• ter_id → Identificador de terminal

• ter_nombre → Nombre de la terminal
  
  

• Condiciones (WHERE) aplicadas:

• Se obtienen únicamente terminales habilitadas (ter_habilitado = 1).

 

• Tipo de unión con otras fuentes (JOIN y llave): Se usa como catálogo para recorrer todas las terminales y generar métricas por día.

• Observaciones (ej. particiones, índices): 

• Actúa como tabla maestra de referencia.

3.6 Conexión / Base: EMPRESARIAL

• Tabla / Recurso: emp_incidencias (alias inc)

• Alias (si aplica): inc

• Campos utilizados (clave → descripción):

• inc_id → Identificador de incidencia

• inc.usercreaid → Usuario creador

• inc_tipo → Tipo de incidencia

• inc_fhincidencia → Fecha de incidencia

• inc_idos → Orden de servicio afectada

• inc_responsable_terminal → Terminal responsable

• inc_descripcion → Descripción de la incidencia
  
  

• Condiciones (WHERE) aplicadas:

• Se incluyen incidencias que no estén eliminadas (eliminado nulo o 0), cuyo inc_descripcion coincida con alguno de tres mensajes predefinidos de fallas o decomisos, y que su inc_idos pertenezca al conjunto de órdenes de servicio analizadas.

 

• Tipo de unión con otras fuentes (JOIN y llave): Relaciona con emp_ordenservicio mediante inc_idos.

• Observaciones (ej. particiones, índices): 

• Se usa para excluir órdenes con incidencias registradas.

3.7 Conexión / Base: EMPRESARIAL

• Tabla / Recurso: emp_adicionales (alias adc)

• Alias (si aplica): adc

• Campos utilizados (clave → descripción):

• adc_ordenservicioid → ID de la orden de servicio

• adc_tipo → Tipo de adicional (E = entrega)

• adc_costo → Costo del adicional

• eliminado → Estado lógico del registro
  
  

• Condiciones (WHERE) aplicadas:

• Se filtran registros con adc_tipo = 'E' (entregas) y, según el bloque, algunos con eliminado = 1.

• Además, se limita a los registros cuyo adc_ordenservicioid esté dentro del conjunto de órdenes seleccionadas o devueltas por la API Rakky.

 

• Tipo de unión con otras fuentes (JOIN y llave): Relaciona con emp_ordenservicio por adc_ordenservicioid.

• Observaciones (ej. particiones, índices): 

• Utilizado para identificar entregas pendientes o completadas.

3.8 Conexión / Base: EMPRESARIAL

• Tabla / Recurso: emp_empresa

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• ruc → Documento de la empresa

• grupo → Tipo de grupo (CORPORATIVO / CREDITO / COMERCIAL)
  
  

• Condiciones (WHERE) aplicadas:

• Filtrar registros donde grupo no sea nulo ni vacío, clasificando las empresas según su tipo de grupo.

 

• Tipo de unión con otras fuentes (JOIN y llave): Se cruza lógicamente con remitentes y destinatarios de emp_ordenservicio.

• Observaciones (ej. particiones, índices): 

• Define categorías de empresa para clasificar los montos de servicio.

4) Filtros globales del reporte

• Inclusiones (must-have):

• Órdenes activas (ose_estado=1), no eliminadas, no anuladas.

• Incidencias no críticas.

• Terminales habilitados.

• Exclusiones (reglas de descarte):

• tipo_os = 'Retiro de mercadería'

• ose_estadoPago IN ('AN','DA')

• ose_tipoanulado != ''

 

• Reglas por estado / habilitado:  Solo estado=1 para registros logísticos.

• Parámetros externos (si el usuario puede filtrarlo): $first_date, $second_date, $terminal

5) Transformaciones y Reglas de negocio

• Derivaciones de campos (cómo se calculan):

• kilaje_aereo → suma de detalle_mercaderia.general

• corporativo_* / comercial_* → según grupo del RUC remitente/destinatario.

• shalom_pro / envia_ya → según valor de rcontacto (WEB o REGISTRA).

• cantidad_reparto_pendiente → diferencia entre entregas registradas vs confirmadas Rakky.

• Mapeos de estado: 

• Terminal (ter_id → ter_nombre)

• Grupo empresa (grupo → tipo_cliente)
  
  

• Reglas de validación (p.ej., sólo registros validados): Ignorar incidencias SUNAT o faltantes.
  
  

• Reglas condicionales (si X entonces Y):

• Si $terminal != "TODOS" → aplica filtro específico.

• Si detalle_mercaderia no es JSON → inicializa vacío.

6) Estructura de salida

• Tabla/archivo destino: report_shipping_amount_part_two_YYYY_MM

• Particionado / sufijo: mensual (date("Y_m", $fecha))

• Clave(s) primaria(s) o únicas: fecha, terminal_id

• Columnas del reporte (nombre → tipo → descripción):

• fecha → DATE → Día del registro  

• terminal_id → INT → Identificador del terminal  

• terminal_nombre → VARCHAR(150) → Nombre del terminal  

• envia_ya → INT → Envíos registrados por el canal Envia Ya  

• shalom_pro → INT → Envíos realizados vía portal Shalom Pro  

• contador_rakki → INT → Cantidad de entregas confirmadas por Rakky  

• monto_rakki → DOUBLE → Monto total de entregas registradas por Rakky  

• cantidad_store → INT → Cantidad de ventas en Shalom Store  

• monto_store → DOUBLE → Monto total de ventas en Shalom Store  

• corporativo_cantidad → INT → Cantidad de envíos de clientes corporativos  

• corporativo_monto → DOUBLE → Monto total de envíos corporativos  

• comercial_cantidad → INT → Cantidad de envíos de clientes comerciales  

• comercial_monto → DOUBLE → Monto total de envíos comerciales  

• cantidad_enviado_aereo → INT → Total de envíos aéreos emitidos  

• monto_enviado_aereo → DOUBLE → Monto total de envíos aéreos emitidos  

• cantidad_recibido_aereo → INT → Total de envíos aéreos recibidos  

• monto_recibido_aereo → DOUBLE → Monto total de envíos aéreos recibidos  

• aereo_entregado_no → INT → Cantidad de envíos aéreos no entregados  

• kilaje_aereo → DOUBLE → Kilaje total de envíos aéreos  

• cantidad_dhl → INT → Cantidad de comprobantes procesados por DHL  

• kilaje_dhl → DOUBLE → Kilaje total asociado a DHL  

• amount_dhl → DOUBLE → Monto total asociado a DHL  

• cantidad_reparto_total → INT → Total de entregas locales realizadas  

• cantidad_reparto_pendiente → INT → Total de entregas locales pendientes  

• cantidad_envios_terrestres_por_aereo → INT → Total de envíos terrestres procesados vía aéreo  

• monto_envios_terrestres_por_aereo → DOUBLE → Monto total de envíos terrestres procesados vía aéreo  

• created_date → DATETIME → Fecha de generación del reporte

• Ordenamiento por defecto: por fecha ascendente y terminal_id

7) Frecuencia y operación

• Frecuencia de actualización:  PENDIENTE (Esperando info de Eduardo)

• Ventana que recalcula (días/meses):  rango dinámico ($first_date → $second_date)

• Tamaño de lote / paginado (chunking): 900 registros por inserción (comentado)

• Tolerancia a fallos / reintentos: manejo básico de cURL error

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

8) Calidad y controles

• Validaciones previas/post:

• JSON válido en detalle_mercaderia

• Rango de fechas correcto
  
  

• Controles de duplicados: Conteos por terminal consistentes con datos API.

• Métricas de completitud (qué se monitorea):  Llave terminal_id + fecha asegura unicidad.

• Cantidades y montos por tipo (aéreo, terrestre, corporativo, comercial).

9) Dependencias externas

• APIs / servicios y endpoints: 

• Rakky (servicio de entregas): 

• Endpoint: DIRRAKKY/api/search_deliveries_by_ose_ids_new

• Función: Verificación de entregas efectivas según lista de órdenes de servicio (OSE).
  
  

• Shalom Store (servicio de ventas físicas):

• Endpoint: RECURSOS_HUMANOS/api/detail-shalom-store-selling

• Función: Consulta de ventas por terminal en el rango de fechas del reporte.
  
  

• Bases de datos internas:

• centos (operativa / logística aérea)

• empresarial (operativa ERP principal)

• Autenticación / headers:  No explícitos. Uso directo de GuzzleHttp\Client->request() y curl_init() sin encabezados personalizados o tokens.

• Mapeos y contratos de datos: 

• Rakky: espera un cuerpo JSON con la clave ose_ids (array de identificadores de órdenes).

• La respuesta esperada es JSON con campo message → lista de entregas confirmadas.
  
  

• Shalom Store: recibe { fh_init, fh_end } como cuerpo del POST.

• Devuelve JSON con message → array de objetos que contienen terminal, ventas_cantidad, ventas_monto.

• Bases internas: devuelven conjuntos de registros (arrays asociativos) para cada consulta SQL (DB::connection()->select()).

10) Historial de cambios

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