Documentación Técnica y Funcional: Módulo de Finanzas

Módulo: Finanzas (FinancialsPreview.tsx y submódulos en src/components/financials/)
Fecha: Septiembre 2026
Propósito: Documentar la arquitectura integral, sub-vistas, flujos de datos, conciliación contable y hoja de ruta de mejoras para la administración, directorio y residentes.

1. Propósito y Filosofía del Módulo

El Módulo de Finanzas es el núcleo de visibilidad, gobernanza y rendición de cuentas del condominio. Integra la información proveniente de:

Cobranza y Cuentas por Cobrar: Adeudos emitidos, pagos registrados y saldos a favor de viviendas.
Tesorería y Bancos: Saldos iniciales, depósitos, dispersiones y movimientos bancarios.
Egresos y Proveedores: Facturación, pagos a proveedores, contratos y asignación presupuestaria.
Fondos Especiales: Fondo Operativo, Fondo de Reserva y Proyectos Extraordinarios.

Objetivos Clave:

Transparencia Total: Proveer reportes claros e inmutables para asambleas de copropietarios y auditorías.
Trazabilidad Lineal: Que cada peso que entra o sale tenga una contraparte documental (folio, factura, comprobante bancario).
Conciliación Matemática: Garantizar que el saldo final reportado coincida al centavo con el saldo de las cuentas bancarias reales.

2. Arquitectura de Componentes

El módulo opera bajo una arquitectura de orquestador central con subvistas desacopladas:

                              ┌──────────────────────────────────────────────┐
                              │            FinancialsPreview.tsx             │
                              │         (Orquestador Principal)              │
                              └──────────────────────┬───────────────────────┘
                                                     │
         ┌───────────────────┬───────────────────────┼───────────────────────┬───────────────────┐
         ▼                   ▼                       ▼                       ▼                   ▼
┌─────────────────┐ ┌─────────────────┐   ┌─────────────────────┐   ┌─────────────────┐ ┌─────────────────┐
│ Financial       │ │ Consolidated    │   │ DetailedIncome      │   │ Receivables     │ │ Funds           │
│ SummaryView     │ │ ReportView      │   │ ExpenseView         │   │ ReportView      │ │ ReportView      │
│ (Resumen KPIs)  │ │ (Consolidado)   │   │ (Libro Mayor Lin.)  │   │ (Cuentas Cobrar)│ │ (Fondos)        │
└─────────────────┘ └─────────────────┘   └─────────────────────┘   └─────────────────┘ └─────────────────┘
                                                     │
                                     ┌───────────────┴───────────────┐
                                     ▼                               ▼
                          ┌─────────────────────┐         ┌─────────────────────┐
                          │ ExpenseFinancial    │         │ Auditoría Estados   │
                          │ AnalysisView        │         │ de Cuenta (Inline)  │
                          │ (Gráficos Egresos)  │         │                     │
                          └─────────────────────┘         └─────────────────────┘

3. Desglose Detallado de las 7 Subvistas

Subvista 1: Resumen Financiero (`summary` - `FinancialSummaryView.tsx`)

Audiencia: Administrador general, Comité de Vigilancia, Directorio.
Función: Panel de mando ejecutivo (Dashboard) de salud financiera.
Métricas e Indicadores Clave (KPIs):
- Saldo Total Disponible: Suma de todas las cuentas bancarias y cajas chicas activas.
- Ingresos del Mes: Total efectivamente cobrado en el periodo actual.
- Egresos del Mes: Total devengado/pagado a proveedores.
- Flujo Neto del Mes: Diferencial operativo ($Ingresos - Egresos$).
- Cuentas por Cobrar Totales: Cartera vencida acumulada por viviendas morosas.
- Índice de Morosidad: Porcentaje de viviendas al corriente vs. con adeudo.
Gráficos:
- Tendencia mensual de ingresos vs. egresos a lo largo de los últimos 6 o 12 meses.
- Distribución del saldo en bancos por cuenta.

Subvista 2: Reporte Consolidado (`consolidated` - `ConsolidatedReportView.tsx`)

Audiencia: Asambleas Generales, Revisores Fiscales, Publicación Mensual.
Función: Estado de Flujo de Efectivo Oficial (Cash Flow) del periodo seleccionado.
Estructura Contable del Reporte:
1. Saldo Inicial en Bancos: Balance bancario exacto al inicio del periodo ($t < startDate$).
2. Ingresos del Periodo:
  - Cuotas de Mantenimiento Ordinarias (por vivienda).
  - Cuotas Extraordinarias y Fondos Especiales.
  - Ingresos Diversos / Intereses / De Terceros (con opción de alternar su visibilidad).
3. Egresos del Periodo:
  - Desglose jerárquico por Partida Presupuestaria y Subpartida.
  - Indicación de facturas, folios y proveedores beneficiarios.
4. Flujo Neto Operativo: $\sum \text{Ingresos} - \sum \text{Egresos}$.
5. Saldo Final Conciliado en Bancos: $\text{Saldo Inicial} + \text{Flujo Neto}$.
Herramientas de Exportación: Descarga en Excel/CSV, generación de PDF oficial con cabecera institucional y función de impresión optimizada (@media print).

Subvista 3: Control de Ingresos y Egresos a Detalle (`detailed_control` - `DetailedIncomeExpenseView.tsx`)

Audiencia: Administrador Contable, Auditor Interno, Tesorero.
Función: Libro Mayor Cronológico Continuo (implementado bajo la regla del Punto 3).
Comportamiento:
- Intercala en una sola tabla cronológica estricta todas las entradas (ingresos) y salidas (egresos).
- En caso de misma fecha, muestra primero los ingresos y luego los egresos.
- Saldo Progresivo Fila por Fila: Cada transacción calcula en tiempo real el saldo resultante acumulado: $$\text{Saldo}i = \text{Saldo} + \text{Ingreso}_i - \text{Egreso}_i$$
- Filtros Avanzados en Vivo:
  - Por Tipo: Todos / Solo Ingresos / Solo Egresos.
  - Por Cuenta Bancaria o Caja Chica.
  - Por Partida / Categoría presupuestaria.
  - Por Beneficiario (Proveedor o Vivienda).
  - Por Fondo (Ordinario / Reserva / Extraordinario).
  - Buscador general por concepto o folio de referencia.
- Exportación: Exporta a CSV y PDF respetando el orden y los filtros activos en pantalla.

Subvista 4: Cuentas por Cobrar (`receivables` - `ReceivablesReportView.tsx`)

Audiencia: Administración, Cobranza, Comité de Mediación.
Función: Monitoreo y gestión de cartera de propietarios.
Modalidades de Visualización:
- Modo Agrupado (Resumen por Vivienda): Muestra cada unidad habitacional con su propietario, saldo anterior, cargos generados en el mes, pagos aplicados, saldo final y saldo a favor (crédito).
- Modo Desglosado (Kardex Detallado): Expande cada vivienda para mostrar la bitácora histórica de cada cuota vencida, recargos y recibos de pago vinculados.
Semáforo de Morosidad:
- Verde: Al corriente ($Saldo \le 0$).
- Amarillo: Deuda reciente ($\le 30$ días).
- Rojo: Deuda morosa o crítica ($> 60-90$ días o más de 2 cuotas).
Acceso Directo: Botón de un solo clic para abrir el Estado de Cuenta individual de la vivienda.

Subvista 5: Fondos (`funds` - `FundsReportView.tsx`)

Audiencia: Consejo de Administración, Asamblea.
Función: Supervisión de la segregación patrimonial y reservas financieras.
Categorías de Fondo:
1. Fondo Operativo: Recursos para gastos recurrentes del día a día (vigilancia, limpieza, servicios públicos).
2. Fondo de Reserva: Fondo legal o estatutario para imprevistos mayores (daños estructurales, reposición de bombas).
3. Fondo Extraordinario: Cuotas aprobadas para proyectos específicos (impermeabilización, remodelación de fachada).
Visualización:
- Matriz mensual de aportaciones vs. erogaciones por cada fondo.
- Gráfico comparativo de acumulación patrimonial.

Subvista 6: Análisis de Egresos (`expenses` - `ExpenseFinancialAnalysisView.tsx`)

Audiencia: Administración y Comités Técnicos.
Función: Business Intelligence (BI) sobre el gasto del condominio.
Visualizaciones:
- Diagrama de pastel (Donut Chart) de egresos por partida mayor.
- Concentración de proveedores (análisis Pareto 80/20 de contratistas).
- Desglose por método de pago (transferencia, cheque, efectivo de caja chica).

Subvista 7: Auditoría de Estados de Cuenta (`statements` - Integrada en `FinancialsPreview.tsx`)

Audiencia: Administración y Atención a Residentes.
Función: Matriz global de estados de cuenta de todas las unidades del condominio.
Características:
- Búsqueda en tiempo real por número de casa/departamento, nombre de propietario o ID.
- Filtro por estado: Todos, Con adeudo, Al corriente, Con saldo a favor.
- Gráfico de distribución de cartera.
- Exportación integral a Excel/CSV y PDF de la sábana de estados de cuenta para respaldo contable.

4. Fuentes de Datos y Modelo Contable

El módulo consume las siguientes entidades definidas en src/types.ts:

Entidad	Origen en Estado	Uso en Finanzas
`HousingUnit[]`	`useCondoState` (`units`)	Catálogo de condóminos, cuotas alícuotas y saldos a favor (`creditBalance`).
`BankAccount[]`	`useCondoState` (`bankAccounts`)	Cuentas bancarias operativas y saldos iniciales de apertura.
`BankMovement[]`	`useCondoState` (`bankMovements`)	Registro de transacciones bancarias (depósitos de residentes, retiros).
`ExpenseRecord[]`	`useCondoState` (`expenses`)	Registro de gastos devengados y pagados con proveedor, categoría y comprobante.
`GeneratedDebt[]`	`useCondoState` (`generatedDebts`)	Cuotas emitidas a las viviendas (ordinarias, multas, intereses, extras).
`RegisteredPaymentRecord[]`	`useCondoState` (`paymentRecords`)	Recibos de pago aplicados a los adeudos con folio, método y fecha.
`YearlyBudget`	`useCondoState` (`budget`)	Presupuesto anual de referencia para partidas de egreso e ingreso.

5. Prevención de Doble Contabilización (Regla de Oro)

Un error común en software contable es sumar dos veces un egreso: una vez desde la cuenta bancaria y otra desde el registro de egresos.

El sistema implementa la siguiente regla canónica de conciliación:

typescript

expenses.forEach((e) => {
  if (e.date < startDate && e.status !== 'cancelled') {
    // Si el egreso ya generó un movimiento bancario registrado, NO se resta dos veces
    const isAlreadyInBank = bankMovements.some((m) => m.expenseId === e.id);
    if (!isAlreadyInBank) {
      balance -= e.amount;
    }
  }
});

Si un egreso pagado está asociado a un bankMovement con expenseId, el saldo bancario real ya lo tiene descontado.
Si un egreso fue capturado antes de que se registrara el movimiento bancario o fue pagado en efectivo de caja chica, se deduce explícitamente.

6. Opciones de Desarrollo Futuro y Recomendaciones

A. Integración de la Vista "Presupuesto vs. Real" como 8va Subvista

Propuesta: Incorporar la comparativa de presupuesto como una pestaña adicional en Finanzas (budget_comparison).
Beneficio:
- Permite a los miembros del Directorio y residentes consultar en el mismo módulo financiero cómo va la ejecución de las cuotas sin tener que entrar a "Editar Presupuesto".
- Se vincula directamente con los datos de ingresos explicados en PRESUPUESTO-VS-REAL.md.

B. Cierre Contable Mensual (Period Lock)

Implementar un switch de "Periodo Cerrado" para meses anteriores.
Evita que operadores agreguen o modifiquen facturas con fecha retroactiva a periodos ya aprobados por asamblea.

C. Portal de Transparencia para Residentes

Configurar una vista restringida del Módulo de Finanzas para el rol resident, ocultando datos personales de terceros o identificadores fiscales sensibles, pero manteniendo acceso a los gráficos de ingresos, egresos y fondos comunitarios.

Documentación Técnica y Funcional: Módulo de Finanzas ​

1. Propósito y Filosofía del Módulo ​

Objetivos Clave: ​

2. Arquitectura de Componentes ​

3. Desglose Detallado de las 7 Subvistas ​

Subvista 1: Resumen Financiero (summary - FinancialSummaryView.tsx) ​

Subvista 2: Reporte Consolidado (consolidated - ConsolidatedReportView.tsx) ​

Subvista 3: Control de Ingresos y Egresos a Detalle (detailed_control - DetailedIncomeExpenseView.tsx) ​

Subvista 4: Cuentas por Cobrar (receivables - ReceivablesReportView.tsx) ​

Subvista 5: Fondos (funds - FundsReportView.tsx) ​

Subvista 6: Análisis de Egresos (expenses - ExpenseFinancialAnalysisView.tsx) ​

Subvista 7: Auditoría de Estados de Cuenta (statements - Integrada en FinancialsPreview.tsx) ​

4. Fuentes de Datos y Modelo Contable ​

5. Prevención de Doble Contabilización (Regla de Oro) ​

6. Opciones de Desarrollo Futuro y Recomendaciones ​

A. Integración de la Vista "Presupuesto vs. Real" como 8va Subvista ​

B. Cierre Contable Mensual (Period Lock) ​

C. Portal de Transparencia para Residentes ​