erp-core/docs/02-fase-core-business/MGN-010-financial/especificaciones/INDICE-ET-FINANCIAL.md

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	Schema core_financial	RF-001 a RF-004	Documentado
ET-FIN-backend	Servicios y API REST	RF-001 a RF-004	Documentado
ET-FIN-frontend	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