REPORTE DE GASTOS

Fuente: App\Http\Controllers\Cloud\Reports\Gastos

1) Nombre del reporte

• Nombre: Reporte de Gastos por Carguero Programado
  

• Código/Alias: report_gastos
  

• Responsable: Equipo de Reportes Cloud
  

• Propósito: Consolidar gastos de ruta por carguero programado, con detalle de documentos, validación, estado de pago y datos del chofer/proveedor.
  
  

2) Alcance temporal

• Campo(s) de fecha utilizados (base): cp.cap_fhsalidaprogramada (salida programada del carguero)
  

• Tipo de rango: Personalizado (entre firstDate y secondDate)
  

• Horas: Sí, se incluye día completo por fecha (00:00:00 – 23:59:59)
  

• Zona horaria: Servidor (igual a sistema)
  
  

3) Origen de datos (tablas/APIs)

3.1 Cargueros programados

• Conexión/Base: empresarial
  

• Tabla: emp_cargprogramado (alias cp)
  

• JOIN: LEFT JOIN emp_carguero_new car ON cp.cap_cargid = car.id
  

• Campos:
  

• cp.cap_id (ID carguero programado)
  

• cp.cap_fhsalidaprogramada (fecha/hora base del rango)
  

• cp.cap_rutacarguero (ruta)
  

• cp.cap_tipo_grupo_id (FK a grupo)
  

• car.car_codigo (para “placa” mostrada junto con cap_cargueroid)
  
  

• Condiciones: cp.cap_fhsalidaprogramada BETWEEN [firstDate 00:00:00] AND [secondDate 23:59:59]
  

• Observaciones: Lista base; luego se filtra a los que tienen gastos.
  
  

3.2 Estado de ruta (km final, estado)

• Conexión/Base: choferes
  

• Tabla: emp_ruta_estado
  

• Campos: ruta_estado, kilometraje_arrive, cap_id
  

• Condiciones: ruta_habilitado = '1' y cap_id IN [caps]
  
  

3.3 Grupos de ruta

• Conexión/Base: empresarial
  

• Tabla: emp_grupo_general
  

• Campos: id, nombre
  

• Condiciones: habilitado = 1
  
  

3.4 Abastecimientos (para km final alternativo)

• Conexión/Base: choferes
  

• Tabla: emp_abastecimiento
  

• Campos: kilometraje_fin, cap_id
  

• Condiciones: habilitado = '1' y cap_id IN [caps]
  
  

3.5 Gastos de ruta (detalle principal)

• Conexión/Base: choferes
  

• Tabla: emp_ruta_gastos
  

• Campos:
  

• Chofer: gast_chofer_id AS id_chofer
  

• Documento comprobante: gast_tipo_doc AS tipo_doc, gast_serie AS serie, gast_num_doc AS num_doc
  

• ERP: gast_serie_erp, gast_numero_erp
  

• Gasto: gast_fecha AS fecha, gast_monto AS monto, gast_tipo_gasto AS tipo_gasto, gast_observ AS observacion, gast_galones AS galones, gast_ruta_comp AS foto, gast_validado, gast_id
  

• Relación: cap_id, ruc
  
  

• Condiciones: gast_habilitado = '1' y cap_id IN [caps]
  

• Orden: ORDER BY gast_fecha DESC
  
  

3.6 Motivos de rechazo (gastos no validados)

• Conexión/Base: choferes
  

• Tabla: emp_gastos_motivos
  

• Campos: gast_id, motivo
  

• Condiciones: status = 1 y gast_id IN [ids de gastos]
  
  

3.7 Personas (choferes / proveedores)

• Conexión/Base: empresarial
  

• Tabla: emp_persona
  

• Campos: per_nrodocumento, per_nombrerzsoc, per_apellidopaterno, per_apellidomaterno
  

• Condiciones: per_nrodocumento IN [dni/ruc recolectados]
  
  

3.8 Estados de pago (ERP – Solicitud de Pagos)

• Fuente externa: API ERPNext (Capacitación)
  

• Tabla remota: tabSolicitud de Pagos
  

• Endpoint: method/send-query-database
  

• Consulta: columnas name, estado_documento, number_factura, n_serie
  

• Filtros: number_factura IN %(numero)s AND n_serie IN %(serie)s
  

• Mapeo de Estados:
  

• Por Pagar → PENDIENTE
  

• Pagado → CANCELADO
  

• Pago Rechazado → RECHAZADO
  
  

4) Filtros globales del reporte

• Inclusiones: Sólo cargueros con al menos un gasto asociado.
  

• Exclusiones: Cargueros cuya “placa” (texto en cap_cargueroid) contenga "CARRE" (carretas).
  

• Reglas habilitado/estado:
  

• ruta_habilitado = '1' (estado ruta)
  

• habilitado = 1 (grupos)
  

• gast_habilitado = '1' (gastos)
  

• status = 1 (motivos)
  
  

• Parámetros externos: firstDate, secondDate.
  
  

5) Transformaciones y Reglas de negocio

• Nombre del chofer: concatena per_nombrerzsoc + apellidos por id_chofer desde emp_persona.
  

• Razón social (RUC): idem con ruc.
  

• Fecha/Hora de gasto: gast_fecha → [fecha_gasto, hora_gasto].
  

• Factura (texto): trim(gast_serie_erp + ' - ' + gast_numero_erp, ' - ').
  

• Validación: gast_validado → "SI" / "NO".
  

• Motivo de rechazo: sólo si gast_validado = false, recogido de emp_gastos_motivos.
  

• Estado de pago: por (serie, número) vía API ERP y mapeo de estados.
  

• Km final mostrado: si existe abastecimiento para el cap_id y el gasto tiene galones, dejar vacío; si no, usar kilometraje_arrive de emp_ruta_estado.
  

• Tipo de grupo: buscar nombre por cap_tipo_grupo_id.
  
  

6) Estructura de salida

• Destino: report_gastos (tabla de reportes)
  

• Particionado / sufijo: por mes ($month = Y_m).
  

• Escritura: writeReport('report_gastos', rows, true, 'fecha', $month)
  

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

• id_carguero → int → ID del carguero programado
  

• fecha → date → Fecha de cap_fhsalidaprogramada
  

• hora → time → Hora de cap_fhsalidaprogramada
  

• ruta → string → cap_rutacarguero
  

• tipo_grupo → string → Nombre del grupo (lookup)
  

• placa → string → cap_cargueroid / car_codigo
  

• doc_chofer → string → DNI del chofer (gast_chofer_id)
  

• nombre_chofer → string → Nombre completo (lookup persona)
  

• tipo_doc_comp → string → Tipo de comprobante (gast_tipo_doc)
  

• serie → string → Serie (gast_serie)
  

• numero → string → Número (gast_num_doc)
  

• tipo_gasto → string → Tipo de gasto
  

• ruc → string → RUC del proveedor
  

• razon_social → string → Nombre/razón social (lookup persona)
  

• observacion → string → Observaciones del gasto
  

• monto → decimal(12,2) → Monto del gasto
  

• fecha_gasto → date → Fecha de gast_fecha
  

• hora_gasto → time → Hora de gast_fecha
  

• galones → decimal(10,2) → Galones (si aplica)
  

• km_final → int/string → Km final (según regla de abastecimiento)
  

• validacion → enum('SI','NO') → Validado por ruta
  

• factura → string → Texto “SERIE - NÚMERO” (ERP)
  

• motivo_rechazo → string → Motivo si no validado
  

• estado → enum('PENDIENTE','CANCELADO','RECHAZADO','') → Estado ERP
  

• created_date → datetime → Timestamp de generación
  

• status → tinyint → 1 = activo
  

• Orden por defecto: fecha asc / hora asc (o el que defina el consumidor).
  
  

7) Frecuencia y operación

• Ejecución normal: método update() recorre del mes actual hacia 1 mes atrás.
  

• Frecuencia sugerida: diaria (cierre de día) y mensual (cierre de mes).
  

• Chunking:
  

• IDs (cap_id, gast_id) en bloques de 5000 (array_chunk).
  

• Personas en bloques de 200.
  
  

• Reintentos: rename_retries = 4, rename_backoff_ms = 300.
  

• UTF-8: force_utf8mb4 = true.
  

8) Calidad y controles

• Sólo registros habilitados en cada fuente.
  

• Descartar carretas ("CARRE" en placa).
  

• Evitar filas sin gastos (no se emite para cap_id sin gastos).
  

• Series y números ERP: filtrar vacíos antes de consultar estados.
  

• Consistencia nombres (upper/trim).
  
  

9) Dependencias externas

• ERPNext – Solicitud de Pagos
  

• Endpoint: method/send-query-database
  

• Request: headers con X-API-Key, body con filters, where, sql_query, tables
  

• Contrato: retorna estado_documento, n_serie, number_factura.

10) Historial de cambios

2025-09-01 13:58 - Gian Piero Villanueva Gastello - Documentación inicial