REPORTE CENTRO COSTO AGENCIAS

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

1) Nombre del reporte

• Nombre:  Reporte Centro Costo Agencia

• Código / Alias:  report_centro_costo_agencia

• Responsable:  Equipo de Reportes Cloud

• Propósito (1 línea):

2) Alcance temporal

• Campo(s) de fecha utilizados:

• Rango principal: rango mensual calculado por updateAgencias() a partir de $first_day y $last_day (generado con range_days en utils).
  
  

• Fechas utilizadas en consultas internas: fechas diarias generadas por generateArrayOfDays() (para consultar tablas diarias report_shipping_amount_YYYY_MM_DD).
  
  

• Fechas en filtros de sub-consultas: list_fecha (gastos), start_date (nómina), fecha_de_inicio_contrato (alquileres), ose_fhpreferenciapartida (ordenes de servicio).
  
  

• Tipo de rango (diario / mensual / personalizado): Mensual (el proceso itera por meses; updateAgencias calcula $totalMonths = 6 meses hacia atrás, genera rangos mensuales y los procesa).

• 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: CAPACITACION

• Tabla / Recurso: Requerimiento de Personal Lima

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• name → Identificador del requerimiento.

• fecha_de_requerimiento → Fecha de solicitud de requerimiento.

• _assign → Usuario(s) asignado(s) como reclutador.

• compromiso_cobertura → Fecha de compromiso de cobertura.

• documento_convocatoria → Documento de convocatoria asociado.

• posicion_solicitada → Puesto solicitado.

• estado_rp → Estado del requerimiento de personal.
  
  

• Condiciones (WHERE) aplicadas: Filtra los registros cuya fecha_de_requerimiento se encuentre entre las fechas date_start y date_end.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): Relaciona su campo documento_convocatoria con el campo oportunidad_empleo del recurso CV Filtrado.
  
  

• Observaciones (ej. particiones, índices): Usa índices por fecha (fecha_de_requerimiento) para mejorar el filtrado mensual.

3.2 Conexión / Base: CAPACITACION

• Tabla / Recurso:  CV Filtrado

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• name → Identificador del CV.

• numero_documento → DNI o número de documento del postulante.

• ombre_solicitante → Nombre del postulante.

• puesto_oportunidad → Puesto al que postula.

• oportunidad_empleo → Documento de convocatoria al que aplica.

• creation → Fecha de registro del CV.
  
  

• Condiciones (WHERE) aplicadas: Filtra los registros cuyo oportunidad_empleo se encuentre dentro de los valores del campo documento_convocatoria de la tabla Requerimiento de Personal Lima.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): JOIN lógico con “Requerimiento de Personal Lima” mediante oportunidad_empleo = documento_convocatoria.
  
  

• Observaciones (ej. particiones, índices): 

• Puede requerir índice en oportunidad_empleo para optimizar la búsqueda por convocatoria.

3.3 Conexión / Base: CAPACITACION

• Tabla / Recurso:  Entrevista

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• name → Identificador del registro de entrevista.

• fecha_entrevista → Fecha de la entrevista.

• contratado → Estado del candidato (Contratado / No Contratado).

• numero_de_documento → Documento del candidato entrevistado.la entrevista.ro de CV.
  
  

• Condiciones (WHERE) aplicadas: Filtra los registros cuyo enlace_cv se encuentre en la lista de identificadores (name) provenientes de CV Filtrado.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): JOIN lógico con CV Filtrado mediante enlace_cv = name.
  
  

• Observaciones (ej. particiones, índices): 

• El campo contratado permite filtrar posteriormente los candidatos contratados.

3.4 Conexión / Base: CAPACITACION

• Tabla / Recurso:  Contrato de Trabajo

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• name → Identificador del contrato.

• fecha_inicio → Fecha de inicio del contrato laboral.

• labor → Puesto o función asignada.

• dni → Documento de identidad del trabajador.
  
  

• Condiciones (WHERE) aplicadas: Filtra los contratos cuyo dni coincida con los numero_de_documento de las entrevistas donde contratado = “Contratado”.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): JOIN lógico con Entrevista mediante dni = numero_de_documento.
  
  

• Observaciones (ej. particiones, índices): 

• Optimiza mediante índices en dni y fecha_inicio.

3.5 Conexión / Base: CAPACITACION

• Tabla / Recurso:  error_reports

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• report → Nombre del reporte con error.

• error → Descripción del error.

• created_date → Fecha de creación del registro de error.
  
  

• Condiciones (WHERE) aplicadas: Inserta un registro solo cuando la tabla report_requerimiento_personal_lima_YYYY_MM no se puede crear correctamente.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): No aplica.
  
  

• Observaciones (ej. particiones, índices): Tabla auxiliar de control de errores generada por el proceso PHP.

3.6 Conexión / Base: CAPACITACION

• Tabla / Recurso:  emp_reportes_validation

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción):

• report → Nombre del reporte ejecutado.

• first_date → Fecha inicial del rango procesado.

• second_date → Fecha final del rango procesado.

• created_date → Fecha y hora de creación del registro.

• status → Estado de la ejecución (1 = Correcto / 0 = Error).
  
  

• Condiciones (WHERE) aplicadas: Se inserta un registro por cada ejecución del método show() indicando el estado de validación del proceso.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): No aplica.
  
  

• Observaciones (ej. particiones, índices): Utilizada como bitácora de control de actualizaciones automáticas de reportes.

3.7 Conexión / Base: CAPACITACION

• Tabla / Recurso:  emp_reportes_validation

• Alias (si aplica): No aplica

• Campos utilizados (clave → descripción): Estructura base de los reportes mensuales que se duplican dinámicamente (ejemplo: report_requerimiento_personal_lima_2025_10).
  
  

• Condiciones (WHERE) aplicadas:

• Usada como plantilla para crear nuevas tablas mensuales mediante:

• CREATE TABLE report_requerimiento_personal_lima_YYYY_MM LIKE report_requerimiento_personal_lima_struct.
  
  

• Tipo de unión con otras fuentes (JOIN y llave): No aplica.
  
  

• Observaciones (ej. particiones, índices): Estructura patrón reutilizada para particionar datos mensuales. 

5) Transformaciones y Reglas de negocio

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

• ventas = sum(enviados + recibidos) por sucursal en el mes (agregado desde tablas diarias).

• 10_porciento (ingreso_ventas) = 0.1 * ventas.

• total_planilla = suma de gross_pay de get_salary_employees por sucursal.

• depositos, gastos_directos, gastos_indirectos = sumas agregadas por agencia desde get_detail_expenses.

• locales = montos de alquileres (o monto por defecto desde branch data) — si moneda USD, se convierte a soles: local_soles = locales * exchange_rate.

• utilidad = ingreso_ventas - (total_planilla + gastos_directos + locales).

• utilidad_porcentaje = utilidad / ingreso_ventas * 100 (cuidado division by zero manejada en código: si ingreso_ventas == 0 → 0).

• personal (porcentual) = total_planilla / ingreso_ventas * 100.

• local (porcentual) = locales / ingreso_ventas * 100.
  
  

• Mapeos de estado: 

• categoria → asignada por assign_category() con rangos: >=15000 → Categoría 1; 10000–14999 → Categoría 2; 5000–9999 → Categoría 2; 2500–4999 → Categoría 4; 1250–2499 → Categoría 5; <1250 → Categoría 6. Además, identificadores 4 y 5 se forzan a Categoría 1.

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

• Si alguna función auxiliar crítica devuelve status:false, agencias() retorna ese error y updateAgencias() guarda el resultado en $updates[$fecha] (registro de fallo).

• Si no existen empleados, salarios o datos de branch el proceso aborta para ese mes (retorna error correspondiente).

• Se valida existencia previa de tablas diarias al iterar (implícito por consulta; si la tabla no existe la consulta falla y se captura el error).
  
  

• Reglas condicionales (si X entonces Y):

• Si get_currency_exchange devuelve tipo de cambio y un rental está en USD → monto se convierte a PEN con exchange_rate.

• Si salaryJSON no contiene una sucursal → la sucursal se salta (continue).

• Si paymentsLocalesJson contiene metraje → se usa ese metraje; en caso contrario se usa metro_fijo desde branch data o valores de dataLocalesCondition.

• Si no hay cvs/datos en subconsulta correspondiente → se generan filas con valores nulos para ciertos campos (comportamiento similar al otro reporte mostrado).

6) Estructura de salida

• Tabla/archivo destino: report_centro_costo_agencia

• Particionado / sufijo: No aplica (tabla única). Observación: los orígenes sí son diarios (report_shipping_amount_YYYY_MM_DD) — la tabla destino no se crea por mes en este fragmento (es fija).
  
  

• Clave(s) primaria(s) o únicas: id → INT AUTO_INCREMENT PRIMARY KEY (definido en $columns).
  
  

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

• id → INT AUTO_INCREMENT → Identificador único de la fila (PK interna)  

• periodo → VARCHAR(20) → Nombre del mes correspondiente (ej. "ENERO")  

• sucursal → VARCHAR(225) → Nombre de la agencia o sucursal  

• id_sucursal → INT → Identificador interno de la sucursal  

• categoria → VARCHAR(20) → Categoría asignada (Categoría 1 a 6)  

• ventas → FLOAT → Total de ventas u operaciones del periodo (envíos + recepciones)  

• n_personas → INT → Número de personas registradas en planilla  

• cant_ope → INT → Cantidad de operaciones u operativos realizados  

• 10_porciento → FLOAT → 10% del total de ventas (ingreso estimado)  

• personal → VARCHAR(20) → Total de gasto en personal (almacenado como texto, evaluable a numérico)  

• servicio → INT → Monto de gastos directos por servicio  

• local → VARCHAR(20) → Monto asociado al local (puede convertirse a valor en soles)  

• utilidad → FLOAT → Utilidad calculada (ingresos menos costos)  

• utilidad_porcentaje → VARCHAR(20) → Porcentaje de utilidad (ej. "12.34 %")  

• personal_porcentaje → VARCHAR(20) → Porcentaje de gasto en personal sobre las ventas  

• local_porcentaje → VARCHAR(20) → Porcentaje de gasto en local sobre las ventas  

• depositos → INT → Total de depósitos por agencia  

• gastos_directos → INT → Total de gastos directos registrados  

• gastos_indirectos → INT → Total de gastos indirectos registrados  

• metraje_m2 → VARCHAR(20) → Metraje del local en metros cuadrados  

• ano → INT → Año correspondiente al periodo  

• created_date → DATETIME → Fecha y hora de creación del registro (DEFAULT CURRENT_TIMESTAMP)  

• status → TINYINT(4) → Estado del registro (1 = activo por defecto)

• Ordenamiento por defecto: No se especifica ORDER BY en el código — el orden depende del insert/DB; para consumo se recomienda ordenar por ano DESC, periodo DESC si se requiere mostrar últimos primero.

7) Frecuencia y operación

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

• Ventana que recalcula (días/meses): Se recalcula por mes (se construyen rangos mensuales con utils->range_days($year,$month,$month)) y, para algunas métricas, se itera por días dentro del mes (consulta diaria de envíos).
  
  

• Tamaño de lote / paginado (chunking): No aplica chunking explícito en updateAgencias() ni en agencias(); las consultas se hacen por mes y por día. (Sin embargo, si la inserción se realiza vía utils->base_report_sin_servicio, ese método podría implementar su propio chunking — no visible en este fragmento).

• Tolerancia a fallos / reintentos: 

• El flujo captura errores de cada función auxiliar: si una función devuelve status:false se propaga y updateAgencias() guarda el resultado en $updates[$fecha] y continúa con los siguientes meses.

• No hay reintentos automáticos explícitos en este código; la tolerancia es registrar el fallo (en $updates) y seguir con la siguiente iteración.
  
  

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

8) Calidad y controles

• Validaciones previas/post:

• Previas: Verificación de existencia y datos devueltos por funciones auxiliares (get_branch_erp, get_branch_empresarial, get_campos_origen_atencion, get_rental_contract, get_currency_exchange, get_detail_expenses, get_employees, get_salary_employees). Si alguna falla, se retorna el error y el mes queda registrado en $updates con ese error.

• Post: updateAgencias() acumula en $updates los resultados por mes (pueden incluir status:false y la causa). No se ve registro en tabla de logs explícita dentro de este fragmento (pero base_report_sin_servicio podría loguear internamente).
  
  

• Controles de duplicados:

• No se aprecia un control explícito de duplicados en el fragmento mostrado. La inserción final via utils->base_report_sin_servicio podría implementar TRUNCATE/UPSERT, pero no está visible aquí. Por ahora: No aplica control de duplicados en este código (revisar implementación de base_report_sin_servicio).
  
  

• Métricas de completitud (qué se monitorea):

• $updates contiene por rango mensual el resultado (éxito/detalle de error) — sirve como métrica operativa de completitud por mes.

• Validaciones de existencia de branch, empleados, salarios y datos de gastos se usan como gates; si faltan, se marca el mes como no procesado.

9) Dependencias externas

• APIs / servicios y endpoints:

• APICAPACITACION → method/send-query-database (usado para múltiples queries sobre: Branch, Currency Exchange, Solicitud de Contratos Alquiler, Employee, Salary Slip, etc.).

• Tablas locales particionadas: report_shipping_amount_YYYY_MM_DD (consultadas por día).

• BD empresarial (empresarial) → tablas: emp_ordenservicio, emp_fn_categorias, emp_fn_list, emp_terminal.
  
  

• Autenticación / headers:

• No se muestran headers ni tokens en el fragmento de código. Llamadas a utils->erp() y general->serviceErp() abstractizan autenticación; revisar utils->erp y general->serviceErp para ver headers / tokens. En el fragmento: No se encontró detalle explícito de autenticación/headers.
  
  

• Mapeos y contratos de datos:

• API send-query-database debe devolver campos indicados por cada sql_query (ej.: exchange_rate, name, ideentificador, categoria, monto_de_local, metro_fijo para branches, etc.).

• Contrato implícito: las tablas diarias report_shipping_amount_YYYY_MM_DD deben tener columnas sent, received, terminal_id para que los aggregados funcionen.

• get_detail_expenses espera que emp_fn_categorias y emp_fn_list existan y devuelvan fn_id, list_monto, list_agencia, list_motivo, list_fecha.

10) Historial de cambios

2025-10-21 13:00 - Elian Franco Arroyo Rodas - Documentación inicial