# US-MGN-004-008-001: Reportes Financieros (Balance General y P&L) **RF Asociado:** [RF-MGN-004-008](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-008-reportes-financieros-balance-y-p&l.md) **Módulo:** MGN-004 - Financiero Básico **Epic:** Reportes Financieros **Prioridad:** P0 (MVP) **Story Points:** 8 **Sprint:** Sprint 13 **Estado:** Ready for Development **Fecha:** 2025-11-24 --- ## User Story **Como** contador o gerente, **Quiero** generar reportes de Balance General y Estado de Resultados (P&L), **Para** analizar la situación financiera de mi empresa en un período determinado. --- ## Descripción Detallada Reportes financieros básicos: **Balance General (Balance Sheet):** - Activos = Pasivos + Patrimonio - Muestra saldos de cuentas al cierre del período - Agrupa por tipo: Activos Corrientes, No Corrientes, Pasivos, Patrimonio - Filtros: fecha_corte, comparar_con_periodo_anterior **Estado de Resultados (Profit & Loss / P&L):** - Ingresos - Gastos = Utilidad Neta - Muestra movimientos del período (no saldos acumulados) - Agrupa por tipo: Ingresos, Costo de Ventas, Gastos Operacionales, Otros Gastos - Filtros: date_from, date_to --- ## Criterios de Aceptación ### Escenario 1: Generar Balance General **Dado que** soy contador, **Cuando** solicito GET /financial/reports/balance-sheet?as_of_date=2024-12-31, **Entonces** recibo reporte con: - Activos Corrientes (suma de cuentas tipo asset) - Pasivos Corrientes (suma de cuentas tipo liability) - Patrimonio (suma de cuentas tipo equity) - Validación: Total Activos = Total Pasivos + Patrimonio ### Escenario 2: Generar Estado de Resultados (P&L) **Dado que** solicito GET /financial/reports/profit-loss?date_from=2024-01-01&date_to=2024-12-31, **Entonces** recibo reporte con: - Total Ingresos (suma de créditos en cuentas income) - Total Gastos (suma de débitos en cuentas expense) - Utilidad Neta = Ingresos - Gastos ### Escenario 3: Filtrar por jerarquía de cuentas **Dado que** cuentas tienen jerarquía (parent_id), **Cuando** genero reporte, **Entonces** totales se agrupan por cuenta padre (ej: 1.1 Activos Corrientes = suma de 1.1.01 + 1.1.02 + ...). ### Escenario 4: Exportar a PDF **Dado que** visualizo Balance General, **Cuando** hago clic en "Exportar PDF", **Entonces** descargo PDF con logo empresa, período, y datos tabulados. ### Escenario 5: Comparar con período anterior **Dado que** solicito balance con compare=true, **Cuando** genero reporte, **Entonces** columnas: Período Actual | Período Anterior | Variación %. --- ## Reglas de Negocio - **RN-1:** Balance General usa saldos acumulados (balance_debit, balance_credit). - **RN-2:** P&L usa movimientos del período (sum de journal_entry_lines filtradas por fecha). - **RN-3:** Balance: Assets = Liabilities + Equity. - **RN-4:** P&L: Net Income = Income - Expenses. - **RN-5:** Solo considerar journal entries con state='posted'. - **RN-6:** Jerarquía de cuentas: calcular totales recursivamente. - **RN-7:** Montos en moneda base de la empresa. - **RN-8:** RLS filtra por company_id. --- ## Tareas Técnicas ### Backend - [ ] GET /api/v1/financial/reports/balance-sheet - [ ] GET /api/v1/financial/reports/profit-loss - [ ] GET /api/v1/financial/reports/trial-balance (balanza) - [ ] GET /api/v1/financial/reports/general-ledger (libro mayor) - [ ] DTO: ReportPeriodDto (date_from, date_to, as_of_date, compare) - [ ] Service: FinancialReportService.generateBalanceSheet() - [ ] Service: FinancialReportService.generateProfitLoss() - [ ] Lógica: Calcular saldos por tipo de cuenta - [ ] Lógica: Agrupar por jerarquía de cuentas (CTE recursivo) - [ ] Lógica: Comparación con período anterior - [ ] Exportación: PDF usando pdfkit - [ ] Exportación: Excel usando xlsx - [ ] Unit tests (10 test cases) - [ ] Integration tests (8 test cases) ### Frontend - [ ] Página: BalanceSheetPage.tsx (/financial/reports/balance-sheet) - [ ] Página: ProfitLossPage.tsx (/financial/reports/profit-loss) - [ ] Componente: BalanceSheetReport.tsx (tabla balance) - [ ] Componente: ProfitLossReport.tsx (tabla P&L) - [ ] Componente: ReportFilters.tsx (date pickers, compare checkbox) - [ ] Botones: [Exportar PDF] [Exportar Excel] - [ ] Tabla jerárquica: indentación por niveles - [ ] API client: financialReportApi.getBalanceSheet(), getProfitLoss() - [ ] Component tests (5 test cases) - [ ] E2E test: "should generate balance sheet and P&L" ### Database - [ ] Query: Calcular saldos por tipo cuenta - [ ] Query: CTE recursivo para jerarquía - [ ] Índices: Optimizar queries de reportes (idx_journal_entry_lines_account_id, idx_journal_entry_lines_date) --- ## Mockups / Wireframes **Balance General:** ``` ┌──────────────────────────────────────────┐ │ Balance General al 31/12/2024 │ │ [Exportar PDF] [Exportar Excel] │ ├──────────────────────────────────────────┤ │ ACTIVOS │ │ Activos Corrientes: 50,000.00 │ │ 1.1.01 Caja 5,000.00 │ │ 1.1.02 Bancos 35,000.00 │ │ 1.1.03 Cuentas por Cobrar 10,000.00 │ │ Activos No Corrientes: 100,000.00 │ │ ──────────────────────────────────── │ │ TOTAL ACTIVOS: 150,000.00 │ │ │ │ PASIVOS │ │ Pasivos Corrientes: 30,000.00 │ │ 2.1.01 Cuentas por Pagar 30,000.00 │ │ ──────────────────────────────────── │ │ TOTAL PASIVOS: 30,000.00 │ │ │ │ PATRIMONIO │ │ 3.1.01 Capital 100,000.00 │ │ 3.2.01 Utilidades Acum. 20,000.00 │ │ ──────────────────────────────────── │ │ TOTAL PATRIMONIO: 120,000.00 │ │ │ │ TOTAL PASIVOS + PATRIMONIO: 150,000.00 ✓│ └──────────────────────────────────────────┘ ``` **Estado de Resultados:** ``` ┌──────────────────────────────────────────┐ │ Estado de Resultados 01/01 - 31/12/2024 │ ├──────────────────────────────────────────┤ │ INGRESOS │ │ 4.1 Ventas de Productos: 80,000.00 │ │ 4.2 Servicios: 20,000.00 │ │ ──────────────────────────────────── │ │ TOTAL INGRESOS: 100,000.00 │ │ │ │ GASTOS │ │ 5.1 Costo de Ventas: 40,000.00 │ │ 5.2 Gastos Operacionales: 30,000.00 │ │ 5.3 Gastos Financieros: 5,000.00 │ │ ──────────────────────────────────── │ │ TOTAL GASTOS: 75,000.00 │ │ │ │ ══════════════════════════════════════ │ │ UTILIDAD NETA: 25,000.00 │ └──────────────────────────────────────────┘ ``` --- ## Casos de Prueba 1. **TC-001:** Generar Balance General correctamente 2. **TC-002:** Validar Assets = Liabilities + Equity 3. **TC-003:** Generar P&L correctamente 4. **TC-004:** Calcular Net Income = Income - Expenses 5. **TC-005:** Agrupar por jerarquía de cuentas 6. **TC-006:** Filtrar por rango de fechas 7. **TC-007:** Comparar con período anterior 8. **TC-008:** Exportar a PDF 9. **TC-009:** Exportar a Excel 10. **TC-010:** RLS filtra por empresa --- ## Dependencias - **US bloqueantes:** - US-MGN-004-001-001 (CRUD Cuentas) - US-MGN-004-003-002 (Postear Asientos) - **Módulos:** MGN-004 - **Librerías:** pdfkit (PDF), xlsx (Excel) --- ## Notas de Implementación - **Cálculo de saldos:** Usar campos precalculados `accounts.balance_debit` y `accounts.balance_credit` para Balance General - **P&L:** Query directo a `journal_entry_lines` con filtro por fecha y tipo de cuenta - **Jerarquía:** CTE recursivo para sumar totales de cuentas hijas - **Performance:** Cachear resultados de reportes en Redis (TTL 5 minutos) - **PDF:** Logo de empresa, formato profesional, saltos de página - **Excel:** Múltiples hojas (Balance Sheet, P&L, Trial Balance) --- ## Estimación Detallada | Tarea | Estimación | |-------|------------| | Backend (queries + services) | 4 horas | | Frontend (reportes + gráficos) | 3 horas | | Exportación PDF/Excel | 2 horas | | Testing | 2 horas | | Code Review | 1 hora | | **TOTAL** | **12 horas = 8 SP** | --- ## Definition of Done - [ ] Balance General genera correctamente - [ ] P&L genera correctamente - [ ] Jerarquía de cuentas funciona - [ ] Exportación PDF funciona - [ ] Exportación Excel funciona - [ ] Comparación períodos funciona - [ ] Tests pasando (>80%) - [ ] Code review aprobado - [ ] Merge a develop - [ ] QA validado (verificar cálculos contables) - [ ] PO aprobado --- ## Referencias - [RF-MGN-004-008](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-008-reportes-financieros-balance-y-p&l.md) - [ET-BACKEND-MGN-004-008](../../02-modelado/especificaciones-tecnicas/backend/mgn-004/ET-BACKEND-MGN-004-008-reportes-financieros-balance-y-p&l.md) - [TRACEABILITY-MGN-004.yaml](../../02-modelado/trazabilidad/TRACEABILITY-MGN-004.yaml)