# 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.