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