# REPORTE ENVIOS COMERCIAL CORPORATIVO

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

## 1) Nombre del reporte

- **Nombre:** Reporte Envios Comercial Corporativo
- **Código / Alias:**  report\_envios\_comercial\_corporativo\_
- **Responsable:** Equipo de Reportes Cloud
- **Propósito (1 línea):**

## 2) Alcance temporal

- **Campo(s) de fecha utilizados:**
    
    
    - `ose_fhpreferenciapartida` (fecha de partida de orden de servicio)
    - `inc_fhincidencia` (fecha de incidencia)
    - `fecha_preferencial` (fecha referencial alternativa)
    - `created_date` (fecha de registro en validación)
- **Tipo de rango (diario / mensual / personalizado):**
    
    
    - Calculado automáticamente entre `$first_date` y `$second_date` por mes, con lógica de retroceso de hasta 3 meses según mes actual.
    - En casos especiales (enero a marzo) incluye meses del año anterior.
- **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:**

- **Base principal:** `$this->empresarial` (ERP Empresarial)
- **Base secundaria:** `$this->centos` (ERP Centos)
- **Versionado:** Se elige conexión antigua o actual según el mes/año:
    
    
    - Si `año == 2023` y `mes <= 9` → usa `empresarial_old` y `centosold`
    - Caso contrario → usa `empresarial` y `centos`

**Observación general:**  
El proceso recorre un rango de fechas generado por `obtainRangeDaysByYear()`, ejecutando iterativamente la función `report()` para cada rango mensual.  
Los resultados se registran en la tabla de control `emp_reportes_validation`.

### 🔹 **3.2 Tabla / Recurso:** `emp_empresa`

- **Alias:** `emp`
- **Campos utilizados:**
    
    
    - `id` → Identificador de la empresa
    - `ruc` → Número de documento (clave de relación)
    - `grupo` → Clasificación de empresa (`COMERCIAL` o `CORPORATIVO`)
    - `gestor` → Usuario responsable o gestor asociado
- **Condiciones (WHERE):**
    
    
    - `grupo` **no nulo**
    - `grupo` **en** (‘COMERCIAL’, ‘CORPORATIVO’)
    - `ruc` **no en** (‘20563023016’, ‘20512528458’)
- **Tipo de unión:**
    
    
    - `LEFT JOIN` con `emp_persona` (`emp.ruc = per.per_nrodocumento`)
- **Observaciones:**
    
    
    - Esta tabla define el universo de empresas que serán evaluadas.
    - El resultado alimenta los arreglos `$companys_group` y `$persons`.

### 🔹 **3.3 Tabla / Recurso:** `emp_persona`

- **Alias:** `per`
- **Campos utilizados:** `per_nrodocumento`
- **Unión:** `LEFT JOIN` con `emp_empresa` (`emp.ruc = per.per_nrodocumento`)
- **Observaciones:**
    
    
    - Se usa solo como apoyo para validar la existencia del RUC en personas.
    - Sin filtros directos, dependiente del JOIN principal.

---

### 🔹 **3.4 Tabla / Recurso:** `emp_ordenservicio`

- **Alias:** No declarado
- **Campos utilizados (clave → descripción):**
    
    
    - `ose_id` → ID único de orden
    - `ose_termorigenatencion` → Origen
    - `ose_termdestinoentrega` → Destino
    - `ose_montofinal` → Monto del servicio
    - `ose_fhpreferenciapartida` / `ose_fhpreferencial` → Fechas de referencia
    - `ose_estadoentregado`, `ose_tipoanulado`, `ose_estadoPago`, `eliminado`, `ose_estado`
    - `ose_remiteempresa`, `ose_destinaempresa` → Empresa remitente y destinataria
- **Condiciones (WHERE):**
    
    
    - `ose_estadoPago NOT IN (‘DA’, ‘AN’)`
    - `ose_tipoanulado = ''`
    - `eliminado = '0'`
    - `ose_estado = '1'`
    - `ose_fhpreferenciapartida BETWEEN [first_date 00:00:00, second_date 23:59:59]`
    - `ose_remiteempresa` o `ose_destinaempresa` **pertenecen** a `$companys_group`
- **Observaciones:**
    
    
    - Base principal para obtener **todas las órdenes de servicio** por empresa.
    - Se filtran órdenes válidas, sin anulación, dentro del rango de fechas.

---

### 🔹 **3.5 Tabla / Recurso:** `emp_detalle_comppago`

- **Alias:** `dcp`
- **Unión:** `LEFT JOIN` con `emp_comppago` (`cp.cop_id = dcp.dcp_cop_id`)
- **Campos utilizados:** `dcp_cop_id`, `dcp_ose_id`
- **Condiciones:**
    
    
    - `dcp_ose_id IN (ordenes válidas)`
    - `cp.cop_estado_pago IS NULL` **o** `cp.cop_estado_pago != 'AN'`
- **Observaciones:**
    
    
    - Permite identificar **órdenes sin pago registrado**, que luego se agrupan como **pendientes de pago** (`$pending_payments`).

---

### 🔹 **3.6 Tabla / Recurso:** `emp_os_detalle`

- **Campos utilizados:**
    
    
    - `osd_peso` → Peso de la carga
    - `osd_osid` → ID de la orden de servicio
- **Condiciones:**
    
    
    - `osd_osid IN (ordenes válidas)`
    - `osd_eliminado = '0'`
- **Observaciones:**
    
    
    - Fuente de los valores de **kilogramos transportados**.
    - Se agrupan por OS (`$details_orders_group`).

---

### 🔹 **3.7 Tabla / Recurso:** `emp_procesos_historial_app`

- **Conexión:** `$this->centos`
- **Campos utilizados:** `id`, `idose`, `proceso`, `nombre_metodo`, `status`
- **Condiciones:**
    
    
    - `idose IN (ordenes válidas)`
    - `proceso IN ('embarque','desembarque','inventario')`
    - `nombre_metodo IN (lista de métodos permitidos)`
    - `status = 1`
- **Observaciones:**
    
    
    - Permite validar qué órdenes pasaron por **embarque, desembarque o inventario**.
    - Las faltantes se marcan como **no procesadas** en esas etapas.

---

### 🔹 **3.8 Tabla / Recurso:** `emp_incidencias`

- **Alias:** `inc`
- **Unión:** `LEFT JOIN emp_ordenservicio os ON os.ose_id = inc.inc_idos`
- **Campos utilizados:**
    
    
    - `inc_id`, `inc_tipo`, `inc_fhincidencia`, `inc_idos`, `inc_descripcion`, `inc_responsable_terminal`
    - `ose_remiteempresa`, `ose_destinaempresa`
- **Condiciones:**
    
    
    - `inc.inc_tipo = 'REVISAR'`
    - `inc_fhincidencia BETWEEN rango de fechas`
    - `ose_estadoPago NOT IN (‘DA’, ‘AN’)`
    - `ose_tipoanulado = ''`
    - `ose_estado = 1`
    - `inc.eliminado IS NULL OR inc.eliminado = 0`
    - `inc_descripcion NOT IN (lista de desechos)`
- **Observaciones:**
    
    
    - Registra **incidencias** relevantes (excluye desechos).
    - Genera agrupación por empresa y día (`$incidences_group`).

---

### 🔹 **3.9 Tabla / Recurso:** `emp_incidencias` (SUNAT)

- **Campos utilizados:** `inc_id`, `inc_idos`
- **Condiciones:**
    
    
    - `inc_idos IN (ordenes válidas)`
    - `inc_descripcion IN (‘3.1 M. DECOMISADA POR SUNAT.’, etc.)`
    - `inc_fhincidencia BETWEEN rango de fechas`
    - `eliminado IS NULL OR eliminado = 0`
- **Observaciones:**
    
    
    - Subconsulta específica para **incidencias SUNAT**, agrupadas por `inc_idos`.

---

### 🔹 **3.10 Tabla / Recurso:** `emp_entrega`

- **Campos utilizados:** `ent_id`, `ent_osid`, `ent_persona`, `ent_eliminado`
- **Condiciones:**
    
    
    - `ent_osid IN (ordenes válidas)`
    - `ent_persona IN (‘67676767’, ‘87878787’, ‘98989898’, ‘35353535’)`
    - `ent_eliminado = '0'`
- **Observaciones:**
    
    
    - Identifica entregas específicas a personas clave.
    - Se utiliza para descartar órdenes que ya fueron entregadas.

---

### 🔹 **3.11 Tabla / Recurso:** `emp_adicionales`

- **Campos utilizados:** `adc_id`, `adc_tipo`, `adc_ordenservicioid`, `eliminado`
- **Condiciones:**
    
    
    - `adc_ordenservicioid IN (ordenes válidas)`
    - `eliminado = '1'`
- **Observaciones:**
    
    
    - Separa las guías con **servicios adicionales** (montacarga “M” o embalaje “K”).
    - Las OS con múltiples adicionales son excluidas del conteo final.

---

### 🔹 **3.12 Procedimiento interno:** `obtainRangeDaysByYear()`

- **Propósito:** Genera las fechas `first_day` y `last_day` por mes entre `first_month` y `last_month`.
- **Uso:** Iterar mensualmente en `update()` para llamar a `report($first_date, $second_date)`.

---

### 🔹 **3.13 Tabla de control:** `emp_reportes_validation`

- **Campos:** `report`, `first_date`, `second_date`, `created_date`, `status`
- **Condiciones:** Inserta un registro por ejecución mensual del reporte.
- **Observaciones:**
    
    
    - Registra el resultado de cada iteración (`status = 1` éxito, `0` error).
    - Facilita trazabilidad de generación por rango de fechas.

---

### 🔹 **3.14 Función auxiliar:** `generateArrayOfDays($first, $second)`

- **Propósito:** Devuelve arreglo con todas las fechas entre dos días.
- **Uso:** Agrupar y acumular métricas por día en `$group`.

---

### 🔹 **3.15 Observaciones globales**

- El código combina **consultas cruzadas entre bases** (ERP empresarial y Centos).
- Gran parte del análisis se realiza **en memoria**, agrupando por `ruc` y `fecha`.
- Los índices principales usados:
    
    
    - `ose_id`, `ruc`, `inc_idos`, `ent_osid`, `adc_ordenservicioid`.
- No usa vistas materializadas, pero genera una **tabla lógica mensual consolidada** en memoria para análisis.

## 4) Filtros globales del reporte

- **Inclusiones:**
    
    
    - Empresas con grupo “COMERCIAL” o “CORPORATIVO”.
    - Órdenes en estado activo (`ose_estado = 1`).
    - Procesos con `status = 1`.
- **Exclusiones:**
    
    
    - Empresas con RUC en lista de exclusión.
    - Estados de pago ‘DA’, ‘AN’.
    - Tipos anulados.
    - Incidencias de tipo “DESECHO” o “FALTANTE” definitivo.
- **Reglas por estado / habilitado:**
    
    
    - Solo registros habilitados (`eliminado = 0` o nulo).
- **Parámetros externos:**
    
    
    - Rango de fechas (`first_date`, `second_date`).

## 5) Transformaciones y Reglas de negocio

- **Derivaciones:**
    
    
    - `kilogramo` = suma(`osd_peso`) por orden.
    - `monto_facturacion_pendiente` = total de `monto` en órdenes sin pago.
    - `cantidad_facturacion_pendiente` = conteo de esas mismas órdenes.
- **Mapeos de estado:**
    
    
    - Órdenes no embarcadas, no desembarcadas, no inventariadas se cuentan en grupos `embarque`, `desembarque`, `inventario`.
- **Validaciones:**
    
    
    - Ignora incidencias sin descripción válida.
    - Excluye entregas ya completadas.
- **Condicionales:**
    
    
    - Si `fecha_preferencial` &lt;= `fecha_consult` y está en rango, se usa como fecha principal.
    - Si existe incidencia por RUC y fecha, incrementa campo `incidencia`.


## 6) Estructura de salida

- **Tabla/archivo destino:** `emp_reportes_validation`
- **Particionado / sufijo:**
    
    
    - Por mes (fecha inicial y final del rango procesado)
- **Clave primaria:** `report`, `first_date`, `second_date`
- **Columnas del reporte( nombre → tipo → descripción):**
    
    
    - **report → VARCHAR → Código o identificador del reporte ejecutado**
    - **first\_date → DATE → Fecha inicial del rango consultado**
    - **second\_date → DATE → Fecha final del rango consultado**
    - **created\_date → DATETIME → Fecha y hora de generación del registro**
    - **status → INT → Resultado del procesamiento (1=éxito, 0=error)**
- **Ordenamiento por defecto:**
    
    
    - Por `created_date DESC`

## 7) Frecuencia y operación

- **Frecuencia de actualización:** PENDIENTE (Esperando info de Eduardo)
- **Ventana recalculada:** Hasta 3 meses previos.
- **Tamaño de lote:** Por rango mensual (`obtainRangeDaysByYear`).
- **Tolerancia a fallos:**
    
    
    - Inserta registro en `emp_reportes_validation` con `status = 0` en caso de excepción.
- **Tiempos esperados:** PENDIENTE (Esperando info de Eduardo)

## 8) Calidad y controles

- **Validaciones previas:**
    
    
    - Verificación de rango de fechas válido.
    - Exclusión de registros eliminados o anulados.
- **Post validaciones:**
    
    
    - Inserción de registro en tabla de validación (`status`).
- **Controles de duplicado:**
    
    
    - Evita múltiples inserciones del mismo mes mediante llaves.
- **Métricas de completitud:**
    
    
    - Conteo de órdenes procesadas vs. esperadas por rango.

## 9) Dependencias externas

- **APIs / Servicios:** No aplica.
- **Autenticación / Headers:** No requerido.
- **Mapeos / Contratos:**
    
    
    - Depende del contrato interno entre bases `empresarial` y `centos`.

## 10) Historial de cambios

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