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