# Modelo de datos y reglas de cálculo

## Tablas principales

| Tabla | Contenido | Propietario lógico |
| --- | --- | --- |
| `users` | Identidad, rol, estado, soporte, fechas de acceso y versión del recorrido ya vista | Administración |
| `sessions` | Sesiones activas almacenadas por hash | Sistema |
| `business_profiles` | Tasas y configuración de la proyección | Usuario financiero |
| `monthly_inputs` | Datos mensuales de ventas, compras, planilla y gastos | Usuario financiero |
| `loans` | Créditos, entidad, icono, color, SVG personalizado, capital, TEA, cuotas y desembolso | Usuario financiero |
| `transaction_categories` | Categorías personalizadas de ingreso y egreso | Usuario financiero |
| `transactions` | Movimientos con importe, fecha y detalle | Usuario financiero |
| `audit_log` | Acciones de acceso y administración | Sistema |
| `app_settings` | Configuración global versionada, incluido el recorrido guiado de prueba | Sistema |

Las claves foráneas están activadas. Las sesiones, perfiles y datos asociados se eliminan cuando corresponde mediante las reglas del esquema. SQLite usa modo WAL y un tiempo de espera de cinco segundos.

## Recorrido guiado

El estado global usa dos claves en `app_settings`: `guided_tour_enabled` y `guided_tour_version`. Activar o reiniciar la guía incrementa la versión; cada cuenta conserva en `users.guided_tour_seen_version` la última versión completada u omitida. El recorrido se inicia automáticamente solo cuando está habilitado y la versión global es mayor que la vista por la cuenta. Pausarlo no borra el avance ni altera datos financieros.

Solo la cuenta con rol interno `master` puede activar, pausar o reiniciar el recorrido global. Usuario, gestor y Administrador pueden repetir manualmente su propia guía desde la interfaz.

## Crédito y amortización

La tasa introducida es la tasa efectiva anual. El cálculo convierte la TEA decimal a una tasa efectiva mensual:

```text
i = (1 + TEA)^(1/12) - 1
```

Para una cuota fija se usa:

```text
C = P × [i(1 + i)^n] / [(1 + i)^n - 1]
```

Donde `P` es el capital, `i` la tasa mensual y `n` el número de cuotas. Si la tasa es cero, el capital se divide entre las cuotas. Cada fila calcula interés sobre el saldo inicial; la amortización es la cuota menos el interés. La última fila ajusta la amortización para cerrar el saldo en cero.

## Proyección anual

La proyección comprende doce meses. Las ventas y compras se convierten a importes con IGV para calcular cobranzas y pagos a proveedores. Las políticas de cobro y pago contienen cuatro proporciones para contado, 30, 60 y 90 días y deben sumar uno. Cuando una política es inválida, se usa el patrón seguro 40, 20, 20 y 20 por ciento.

Si una compra mensual no se introduce manualmente, se estima con la tasa de costo de ventas configurada.

## IGV

El débito fiscal proviene de las ventas y el crédito fiscal de las compras. El crédito no utilizado se arrastra al siguiente mes y nunca produce un pago negativo. El pago se desplaza un mes o tres meses cuando se activa la modalidad de IGV Justo.

## Planilla y aportes

El sistema calcula el descuento previsional con la tasa configurada, la planilla neta y el aporte de EsSalud. Los pagos previsionales y de EsSalud se desplazan al mes siguiente. Las tasas son parámetros de simulación y no valores normativos garantizados.

## Renta

Los pagos mensuales a cuenta se estiman con una tasa aplicada a las ventas. Al cierre se estima un impuesto anual sobre la utilidad antes de impuestos y se compara con los adelantos. El resultado puede ser un saldo por regularizar o un exceso estimado.

## Flujo de caja

Los ingresos mensuales incluyen cobranzas, desembolsos de créditos y otros ingresos. Los egresos incluyen planilla neta, pagos a proveedores, servicios, otros gastos, tributos, aportes, cuotas de crédito y otras salidas. El saldo final de cada mes se convierte en el saldo inicial del mes siguiente.

## Validaciones relevantes

- Capital mayor que cero.
- TEA igual o mayor que cero.
- Entre 1 y 360 cuotas.
- Mes de desembolso entre 1 y 12.
- Iconos de crédito validados por identificador alfanumérico seguro (por defecto `'bank'`) y color en formato hexadecimal `#RRGGBB` (por defecto `'#AD0F2F'`).
- Código SVG personalizado validado con etiqueta raíz `<svg>...</svg>`, límite de 5,000 caracteres y sanitización estricta que bloquea scripts, eventos `on*`, `javascript:`, `foreignObject`, `iframe`, `embed` y `object`.
- Movimientos con importe mayor que cero.
- Contraseñas temporales entre 8 y 128 caracteres.
- Importaciones administrativas de hasta 500 cuentas por archivo.
- Correos únicos y sin duplicados dentro del archivo importado.
- Versión del recorrido igual o mayor que cero y actualización global restringida al Administrador.

## Reglas para modificar cálculos

1. Documentar la regla anterior y la nueva en `DECISIONES_TECNICAS.md`.
2. Incorporar o actualizar pruebas en `test/finance.test.js` y, cuando corresponda, `test/api.test.js`.
3. Revisar el efecto sobre totales, gráficos y exportaciones.
4. Registrar la modificación en `REGISTRO_CAMBIOS.md`.
5. Solicitar validación contable antes de presentar el cambio como regla institucional.