REPORTE FACTURA DE VENTA

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

1) Nombre del reporte

• Nombre: Reporte Factura de Venta

• Código / Alias: report_factura_de_venta

• Responsable:  Equipo de Reportes Cloud

• Propósito (1 línea):

2) Alcance temporal

• Campo(s) de fecha utilizados: 

• first_date → Fecha inicio

• second_date → Fecha Fin

• created_date → Fecha de creacion

• Tipo de rango (diario / mensual / personalizado): Mensual (frist_month, last_month)

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

• Zona horaria: la del servidor

3) Origen de datos (tablas/APIs)

• Conexión / Base:  ERP

• Tabla / Recurso: tabSales Invoice

• Alias (si aplica): si

• Campos utilizados (clave → descripción):

• name → Identificador de registro

• docstatus → Estado del documento

• customer → Cliente

• estado → Estado

• factura_tipo → Tipo Factura

• serie → Numero de serie

• n_de_orden_venta →Registro  de Orden de venta Vinculado

• orden_de_trabajo → Registro  de  Orden De trabajo Vinculado 

• placa_id →  Identificador de placa

• placa_vehiculo → Placa de Vehiculo

• numero → Numero

• grand_total → Monto total

• currency → Moneda

• estado_general → Estado general

• posting_date → Fecha de publicacion

• Condiciones (WHERE) aplicadas: devuelve los registros cuya fecha esté dentro del rango indicado y que no tengan estado “Cancelled”

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

• Observaciones (ej. particiones, índices): Hay un particionado temporal: los ranges calculados con first_day y last_day. Se usa para cortar la data por meses.

4) Filtros globales del reporte

• Inclusiones (must-have): 

• Depende de lo que reciba dateUnlimited y el rango de fecha (first_day y last_day)

• Exclusiones (reglas de descarte): No aplica

• Reglas por estado / habilitado: No aplica

• Parámetros externos (si el usuario puede filtrarlo): Si, el usuario puede incluir la fecha inicio y fecha fin en el rango de búsqueda.

5) Transformaciones y Reglas de negocio

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

• Mapeos de estado: No aplica

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

• Reglas condicionales (si X entonces Y):

• Si $dateUnlimited == "TODOS" → recorrer todos los años desde 2021.

• Si $dateUnlimited == "12" → generar rangos mes a mes desde la fecha pivote 2023-09-01.

• Si $dateUnlimited == "8" → tomar últimos 8 meses.

• Si no se cumple ninguno → tomar mes actual y posiblemente diciembre del año anterior.

6) Estructura de salida

• Tabla/archivo destino: report_factura_de_venta

• Particionado / sufijo: no aplica

• Clave(s) primaria(s) o únicas: no aplica

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

• id → INT → Identificador único incremental (clave primaria)  

• name → VARCHAR(50) → Nombre o identificador del registro  

• docstatus → VARCHAR(50) → Estado documental del registro (ej. borrador, validado)  

• customer → VARCHAR(200) → Cliente asociado a la factura  

• estado → VARCHAR(200) → Estado de la factura o transacción  

• factura_tipo → VARCHAR(200) → Tipo de factura (ej. venta, compra)  

• serie → VARCHAR(200) → Serie de la factura  

• n_de_orden_venta → VARCHAR(200) → Número de orden de venta asociada  

• orden_de_trabajo → VARCHAR(200) → Orden de trabajo relacionada  

• placa_id → VARCHAR(200) → Identificador interno de la placa del vehículo  

• placa_vehiculo → VARCHAR(200) → Placa física del vehículo  

• numero → VARCHAR(200) → Número de la factura o documento  

• grand_total → VARCHAR(200) → Importe total de la factura  

• currency → VARCHAR(200) → Moneda en que se registra la transacción  

• estado_general → VARCHAR(200) → Estado general consolidado del documento  

• fecha → VARCHAR(200) → Fecha de emisión o registro  

• created_date → DATETIME → Fecha y hora de creación (por defecto actual)  

• status → TINYINT(4) → Indicador de estado activo/inactivo (1 por defecto) 

• Ordenamiento por defecto: No aplica ORDER BY

7) Frecuencia y operación

• Frecuencia de actualización: Al ejecutarse la función updateFacturaVenta()

• Ventana que recalcula (días/meses): 

• Depende de dateUnlimited:

• "TODOS" → recalcula desde 2021 hasta la fecha actual.

• "12" → recalcula desde un pivote (2023-09-01) mes por mes hasta hoy.

• "8" → últimos 8 meses.

• Vacío o default → solo el mes actual (con excepción de enero/febrero que arrastra diciembre del año anterior).
  
  

• Tamaño de lote / paginado (chunking): 

• Se usa array_chunk($result, 900) → divide la data en lotes de 900 registros antes de insertarlos en BD.

• Tolerancia a fallos / reintentos: Se manejan excepciones con try/catch y \PDOException
  
  

• Tiempos de ejecución esperados: No se especifica

8) Calidad y controles

• Validaciones previas/post:

• Previas:

• Se valida si la tabla existe antes de insertar ($verify = $this->verifyExistTable(...)).

• Si no existe, se inserta un registro en error_reports y se hace continue → es una validación previa para garantizar que la tabla destino esté lista.

• Se maneja el caso especial de enero/febrero para incluir datos del año anterior → valida consistencia temporal.

• Post: 

• Tras cada inserción en lote (insert($arr)), se hace commit() de la transacción.

• Si hay error (catch (\PDOException $e)), se hace rollBack() y se registra el fallo en emp_reportes_validation.

• Controles de duplicados:

• En la lógica de creación de tablas particionadas (CREATE TABLE {$db_name}), que evita que se inserten datos de un rango en la misma tabla dos veces.
  
  

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

• Se insertan logs en emp_reportes_validation con campos:

• report → nombre del reporte.

• first_date, second_date → ventana procesada.

• created_date → cuándo se ejecutó.

• status → 1 (éxito) o 0 (error).

9) Dependencias externas

ERPNext – Factura de venta

• APIs / servicios y endpoints: method/send-query-database

• Autenticación / headers:

• Se envían headers básicos: 

• $options = [

•    'headers' => [

•        "Accept" => "application/json",

•        "Content-Type" => "application/json"

•    ]

• ];

• No aparece un Authorization: Bearer <token> ni otra forma de autenticación explícita.
  
  

• Mapeos y contratos de datos: Se especifica parcialmente en la tabla  report_factura_de_venta de la función updateFacturaVenta() 

10) Historial de cambios

2025-09-19 16:55 - Elian Franco Arroyo Rodas - Documentación inicial