erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-010-generar-reporte-fiscal-mensual.md

US-MAE016-010: Generar reporte fiscal mensual

Metadata

Campo	Valor
ID	US-MAE016-010
Epica	EPIC-MAE-016 - Carta Porte CFDI
Modulo	carta-porte
Prioridad	P2
Story Points	3
Sprint	Por asignar
Estado	Backlog

Historia de Usuario

Como contador, quiero generar un reporte fiscal mensual de todos los CFDI con complemento Carta Porte emitidos y cancelados en un periodo, para conciliar la informacion fiscal, preparar declaraciones y tener un consolidado listo para auditorias del SAT.

Descripcion Detallada

Al cierre de cada periodo contable (mensual o personalizado), el contador necesita un consolidado de todos los CFDI con complemento Carta Porte que se emitieron y cancelaron. Este reporte es esencial para la conciliacion fiscal, la preparacion de declaraciones y la respuesta a requerimientos de informacion del SAT.

El reporte lista cada CFDI con sus datos principales: UUID, serie, folio, tipo de CFDI (Ingreso o Traslado), RFC del receptor, fecha de timbrado, subtotal, total, estado (TIMBRADA o CANCELADA) y motivo de cancelacion cuando aplica. El reporte agrupa los resultados por tipo de CFDI y estado, mostrando subtotales y totales generales. Esto permite al contador verificar rapidamente cuantos CFDI se emitieron por tipo, cuantos se cancelaron y los montos acumulados.

El reporte se puede exportar en formato Excel (XLSX) para manipulacion en hojas de calculo y en formato PDF para archivo formal. Los filtros permiten acotar por tipo_cfdi, estado, rango de fechas, RFC del receptor y serie, dando flexibilidad para generar reportes especificos segun la necesidad.

Criterios de Aceptacion

Escenario 1: Reporte mensual con CFDI vigentes y cancelados

Dado un tenant que en enero 2026 emitio 45 cartas porte de Ingreso (40 timbradas, 5 canceladas) y 10 de Traslado (todas timbradas) Cuando el contador genera el reporte fiscal para enero 2026 Entonces el sistema muestra un listado con 55 registros, agrupado en secciones: "CFDI Ingreso - Timbradas (40): Total $X", "CFDI Ingreso - Canceladas (5): Total $Y", "CFDI Traslado - Timbradas (10): Total $0", con totales generales al final.

Escenario 2: Exportar reporte a Excel

Dado un reporte fiscal generado con datos del periodo Cuando el contador selecciona la opcion "Exportar a Excel" Entonces el sistema genera un archivo XLSX con columnas: UUID, Serie, Folio, Tipo CFDI, RFC Receptor, Nombre Receptor, Fecha Timbrado, Subtotal, Total, Estado, Motivo Cancelacion, y una hoja de resumen con totales por tipo y estado.

Escenario 3: Filtro por tipo de CFDI

Dado que el contador necesita solo los CFDI de Ingreso del periodo Cuando aplica el filtro tipo_cfdi = 'INGRESO' y rango de fechas del mes Entonces el sistema muestra unicamente las cartas porte de tipo Ingreso, excluyendo los de Traslado.

Escenario 4: Periodo sin CFDI emitidos

Dado un tenant que no emitio ningun CFDI con Carta Porte en el periodo seleccionado Cuando el contador genera el reporte Entonces el sistema muestra un mensaje "No se encontraron CFDI con complemento Carta Porte en el periodo seleccionado" y no genera archivo de exportacion.

Tareas Tecnicas

• Database: Consultar compliance.cartas_porte con filtros por tenant_id, estado, tipo_cfdi, rango de fecha_timbrado y fecha_cancelacion; agregaciones por tipo_cfdi y estado para subtotales; usar indices idx_carta_porte_tenant e idx_carta_porte_estado para rendimiento
• Backend: Crear endpoint GET /api/v1/carta-porte/reporte-fiscal con query params: fecha_desde, fecha_hasta, tipo_cfdi, estado, rfc_receptor, serie, formato (json, xlsx, pdf); crear ReporteFiscalService con logica de agrupacion y totalizacion; crear ReporteFiscalResponseDto con arrays de registros y objeto de resumen; implementar generacion de XLSX con libreria (ExcelJS) y PDF (PDFKit/Puppeteer)
• Frontend: Crear vista ReporteFiscalPage con filtros: selector de periodo (mes/anio o rango personalizado), tipo CFDI (dropdown), estado (dropdown), RFC receptor (texto), serie (texto); tabla de resultados con columnas del reporte; seccion de resumen con totales por tipo y estado en tarjetas visuales; botones "Exportar Excel" y "Exportar PDF"
• Tests: Test unitario del servicio de agrupacion y totalizacion; test con periodo con datos mixtos (timbrados y cancelados); test con periodo sin datos; test de generacion de XLSX con estructura correcta; test de filtros individuales y combinados

Dependencias

• Depende de: US-MAE016-003 (Timbrar CFDI - los datos del reporte provienen de cartas porte timbradas y canceladas)
• Bloquea: MAE-018 (Reportes y KPIs - este reporte se integra en el dashboard de KPIs fiscales)

Notas Tecnicas

• El reporte consulta cartas porte con estado TIMBRADA y CANCELADA. Los estados BORRADOR y VALIDADA no se incluyen porque no son documentos fiscales emitidos.
• Para CFDI cancelados, se incluye la fecha de cancelacion (no la fecha de timbrado original) cuando se filtra por periodo de cancelacion.
• El campo fecha_timbrado se usa como fecha principal para el periodo del reporte. Si se requiere tambien por fecha_cancelacion, se ofrece un toggle de "Periodo por fecha de timbrado / fecha de cancelacion".
• El XLSX incluye dos hojas: "Detalle" con todos los registros y "Resumen" con totales agrupados.
• El PDF incluye encabezado con datos del tenant (RFC, razon social), periodo del reporte y pie de pagina con fecha de generacion.
• Para tenants con alto volumen de CFDI (cientos por mes), el reporte debe soportar paginacion en la vista web y generacion completa en la exportacion.
• Los montos se muestran en la moneda original (MXN por defecto) con 2 decimales.