# Indice de Especificaciones Tecnicas - MGN-010 Financial

## Identificacion

| Campo | Valor |
|-------|-------|
| **Modulo** | MGN-010 |
| **Epic** | Base Financiera |
| **Total ET** | 3 |
| **Story Points** | 46 |
| **Fecha** | 2025-12-05 |

---

## Especificaciones Tecnicas

| ID | Titulo | RF Cubiertos | Estado |
|----|--------|--------------|--------|
| [ET-FIN-database](./ET-FIN-database.md) | Schema core_financial | RF-001 a RF-004 | Documentado |
| [ET-FIN-backend](./ET-FIN-backend.md) | Servicios y API REST | RF-001 a RF-004 | Documentado |
| [ET-FIN-frontend](./ET-FIN-frontend.md) | Componentes React + Decimal.js | RF-001 a RF-004 | Documentado |

---

## Resumen de Componentes

### Database (ET-FIN-database)

| Tabla | RF | Descripcion |
|-------|-----|-------------|
| account_types | RF-001 | Tipos de cuenta (global) |
| charts_of_accounts | RF-001 | Planes de cuentas por tenant |
| accounts | RF-001 | Cuentas contables jerarquicas |
| tenant_currencies | RF-002 | Monedas habilitadas por tenant |
| exchange_rates | RF-002 | Tipos de cambio historicos |
| fiscal_years | RF-003 | Anos fiscales |
| fiscal_periods | RF-003 | Periodos contables |
| cost_centers | RF-004 | Centros de costo |
| journal_entries | RF-004 | Asientos contables (cabecera) |
| journal_lines | RF-004 | Lineas de asiento (partida doble) |

**Total:** 10 tablas

**Funciones:**
- `get_exchange_rate()` - Obtener tipo de cambio para fecha
- `get_period_for_date()` - Obtener periodo abierto
- `post_journal_entry()` - Contabilizar asiento atomicamente
- `get_account_balance()` - Saldo de cuenta
- `create_default_chart()` - Crear plan de cuentas base

### Backend (ET-FIN-backend)

| Servicio | Responsabilidad | RF |
|----------|-----------------|-----|
| ChartsService | CRUD planes de cuentas | RF-001 |
| AccountsService | CRUD cuentas, balances | RF-001 |
| CurrenciesService | Monedas, conversiones | RF-002 |
| ExchangeRatesService | Tipos de cambio | RF-002 |
| FiscalYearsService | CRUD anos fiscales | RF-003 |
| FiscalPeriodsService | CRUD periodos, cierre | RF-003 |
| JournalService | Asientos, contabilizacion | RF-004 |
| CostCentersService | CRUD centros de costo | RF-004 |

**Total:** 23 endpoints

---

## Matriz de Trazabilidad RF -> ET

| RF | Database | Backend |
|----|----------|---------|
| RF-FIN-001 | account_types, charts_of_accounts, accounts | ChartsService, AccountsService |
| RF-FIN-002 | tenant_currencies, exchange_rates | CurrenciesService, ExchangeRatesService |
| RF-FIN-003 | fiscal_years, fiscal_periods | FiscalYearsService, FiscalPeriodsService |
| RF-FIN-004 | journal_entries, journal_lines, cost_centers | JournalService, CostCentersService |

---

## Arquitectura Contable

```
+------------------+
| Chart of Accounts|
+--------+---------+
         |
         v
+--------+---------+
|     Accounts     |<--- Jerarquia (LTREE)
|   (Detail/Group) |
+--------+---------+
         |
         v
+--------+---------+     +------------------+
|  Journal Entry   |---->|  Fiscal Period   |
+--------+---------+     +------------------+
         |                        |
         v                        v
+--------+---------+     +------------------+
|  Journal Lines   |     |   Fiscal Year    |
| (Debit/Credit)   |     +------------------+
+------------------+
```

### Flujo de Contabilizacion

1. **Crear asiento** (draft)
   - Validar periodo abierto
   - Obtener tipo de cambio
   - Generar numero secuencial
   - Crear lineas con montos base

2. **Contabilizar** (post)
   - Verificar balance (debito = credito)
   - Actualizar saldos de cuentas
   - Marcar como posted

3. **Reversar** (si necesario)
   - Crear asiento inverso
   - Contabilizar reverso
   - Marcar original como reversed

---

## Precisiones Numericas

| Campo | Tipo | Precision | Uso |
|-------|------|-----------|-----|
| Montos | DECIMAL | 18,4 | Valores monetarios |
| Tipos de cambio | DECIMAL | 18,8 | Tasas de conversion |
| Saldos | DECIMAL | 18,4 | Acumulados de cuenta |

---

## Dependencias Tecnicas

### Externas
- PostgreSQL 15+ (LTREE, DECIMAL, transactions)
- TypeORM 0.3+
- NestJS 10+
- date-fns (manejo de fechas)

### Internas
- core_tenants.tenants (RLS)
- core_catalogs.currencies (catalogo global)
- MGN-001 Auth (Autenticacion)
- MGN-003 RBAC (Permisos)

---

## Permisos Requeridos

| Permiso | Descripcion |
|---------|-------------|
| financial.accounts.read | Ver cuentas y balances |
| financial.accounts.manage | Crear/editar cuentas |
| financial.currencies.read | Ver monedas y tasas |
| financial.currencies.manage | Configurar monedas |
| financial.periods.read | Ver anos y periodos |
| financial.periods.manage | Crear/cerrar periodos |
| financial.journal.read | Ver asientos |
| financial.journal.create | Crear asientos |
| financial.journal.post | Contabilizar asientos |
| financial.journal.reverse | Reversar asientos |
| financial.costcenters.read | Ver centros de costo |
| financial.costcenters.manage | Crear/editar CC |
| financial.reports.read | Ver reportes financieros |

---

## Reportes Derivados

| Reporte | Descripcion | Query Base |
|---------|-------------|------------|
| Balance General | Activo, Pasivo, Capital | Saldos por clasificacion |
| Estado de Resultados | Ingresos vs Gastos | Movimientos del periodo |
| Balanza de Comprobacion | Saldos por cuenta | get_account_balance() |
| Libro Mayor | Movimientos por cuenta | getLedger() |
| Libro Diario | Asientos cronologicos | findAll() |

---

## Integracion con Verticales

```
MGN-010 Financial (Base)
    │
    ├── Facturacion
    │   └── JournalService.create(sourceModule: 'invoicing')
    │
    ├── Cuentas por Cobrar
    │   └── JournalService.create(sourceModule: 'receivables')
    │
    ├── Cuentas por Pagar
    │   └── JournalService.create(sourceModule: 'payables')
    │
    └── Tesoreria
        └── JournalService.create(sourceModule: 'treasury')
```

Cada modulo vertical:
1. Define sus cuentas contables en el plan
2. Genera asientos automaticamente
3. Referencia documentos via `sourceDocumentId`

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial con 2 ET |
| 1.1 | 2025-12-05 | Requirements-Analyst | Agregado ET Frontend |