erp-core/docs/02-fase-core-business/MGN-010-financial/requerimientos/RF-FIN-001.md

RF-FIN-001: Plan de Cuentas

Identificacion

Campo	Valor
ID	RF-FIN-001
Modulo	MGN-010 Financial
Titulo	Plan de Cuentas
Prioridad	P0 - Critica
Estado	Draft
Fecha	2025-12-05

---

Descripcion

El sistema debe permitir definir y gestionar el plan de cuentas contables, con estructura jerarquica, multiples niveles, y soporte para diferentes normativas contables (PCGA, NIIF).

---

Requisitos Funcionales

RF-FIN-001.1: Estructura del Plan de Cuentas

interface ChartOfAccounts {
  id: UUID;
  tenantId: UUID;
  code: string;             // "PCGA-2025"
  name: string;             // "Plan General Contable 2025"
  description?: string;
  standard: AccountingStandard;
  baseCurrencyId: UUID;     // Moneda base
  isActive: boolean;
  createdAt: TIMESTAMPTZ;
  updatedAt: TIMESTAMPTZ;
}

enum AccountingStandard {
  PCGA = 'pcga',           // Plan Contable General
  NIIF = 'niif',           // Normas Internacionales
  US_GAAP = 'us_gaap',     // US Generally Accepted
  CUSTOM = 'custom'         // Personalizado
}

RF-FIN-001.2: Estructura de Cuenta

interface Account {
  id: UUID;
  chartId: UUID;            // FK al plan
  parentId?: UUID;          // FK cuenta padre
  code: string;             // "1.1.01.001"
  name: string;             // "Caja General"
  description?: string;
  accountType: AccountType;
  nature: AccountNature;
  level: number;            // Nivel en jerarquia
  isDetail: boolean;        // Permite movimientos
  isActive: boolean;
  currencyId?: UUID;        // Moneda especifica
  tags?: string[];          // Etiquetas
  createdAt: TIMESTAMPTZ;
  updatedAt: TIMESTAMPTZ;
}

enum AccountType {
  ASSET = 'asset',                    // Activo
  LIABILITY = 'liability',            // Pasivo
  EQUITY = 'equity',                  // Capital
  INCOME = 'income',                  // Ingreso
  EXPENSE = 'expense',                // Gasto
  COST = 'cost',                      // Costo
  CONTRA_ASSET = 'contra_asset',      // Contra-activo
  CONTRA_LIABILITY = 'contra_liability'
}

enum AccountNature {
  DEBIT = 'debit',          // Naturaleza deudora
  CREDIT = 'credit'         // Naturaleza acreedora
}

RF-FIN-001.3: Jerarquia de Cuentas

Estructura tipica:

1. ACTIVO (Grupo)
   1.1. Activo Corriente (Subgrupo)
       1.1.01. Efectivo y Equivalentes (Rubro)
           1.1.01.001. Caja General (Cuenta de detalle)
           1.1.01.002. Bancos (Auxiliar)
               1.1.01.002.001. Banco Nacional - Cuenta 123
       1.1.02. Cuentas por Cobrar
           ...
2. PASIVO
   ...

RF-FIN-001.4: Reglas de Codificacion

interface CodingRules {
  separator: string;        // "." o "-"
  levelLengths: number[];   // [1, 1, 2, 3] = X.X.XX.XXX
  maxLevels: number;        // Maximo niveles permitidos
  autoCode: boolean;        // Generar codigo automatico
}

// Validacion de codigo
function validateAccountCode(code: string, rules: CodingRules): boolean {
  const parts = code.split(rules.separator);
  if (parts.length > rules.maxLevels) return false;
  return parts.every((part, i) => part.length === rules.levelLengths[i]);
}

RF-FIN-001.5: Saldos de Cuenta

interface AccountBalance {
  accountId: UUID;
  periodId: UUID;
  openingDebit: Decimal;
  openingCredit: Decimal;
  movementDebit: Decimal;
  movementCredit: Decimal;
  closingDebit: Decimal;
  closingCredit: Decimal;
  balance: Decimal;         // Saldo final
  balanceInBase: Decimal;   // En moneda base
}

RF-FIN-001.6: Planes de Cuentas Predefinidos

El sistema incluye templates:

Template	Descripcion	Cuentas
PCGA_MX	Plan Contable Mexico	~500
PCGA_CO	Plan Contable Colombia	~450
NIIF_BASIC	NIIF Simplificado	~200
MINIMAL	Minimo funcional	~50

---

Operaciones

Listar Planes de Cuentas

GET /api/v1/financial/charts

Response:
{
  "data": [
    {
      "id": "uuid",
      "code": "PCGA-2025",
      "name": "Plan General Contable 2025",
      "standard": "pcga",
      "accountCount": 250,
      "isActive": true
    }
  ]
}

Obtener Arbol de Cuentas

GET /api/v1/financial/charts/:id/accounts?tree=true

Response:
{
  "chart": { "id": "...", "name": "..." },
  "accounts": [
    {
      "id": "uuid",
      "code": "1",
      "name": "ACTIVO",
      "level": 1,
      "isDetail": false,
      "children": [
        {
          "id": "uuid2",
          "code": "1.1",
          "name": "Activo Corriente",
          "children": [...]
        }
      ]
    }
  ]
}

Crear Cuenta

POST /api/v1/financial/charts/:chartId/accounts
{
  "parentId": "uuid-parent",
  "code": "1.1.01.003",
  "name": "Caja Chica",
  "accountType": "asset",
  "nature": "debit",
  "isDetail": true
}

Obtener Saldo de Cuenta

GET /api/v1/financial/accounts/:id/balance?periodId=uuid

Response:
{
  "accountId": "uuid",
  "accountCode": "1.1.01.001",
  "accountName": "Caja General",
  "period": { "name": "Diciembre 2025" },
  "openingBalance": 50000,
  "movements": {
    "debit": 100000,
    "credit": 80000
  },
  "closingBalance": 70000
}

Importar Plan de Template

POST /api/v1/financial/charts/import
{
  "template": "PCGA_MX",
  "name": "Mi Plan 2025",
  "customizations": {
    "addAccounts": [...],
    "removeAccounts": [...]
  }
}

---

Reglas de Negocio

ID	Regla	Severidad
BR-001	Codigo de cuenta unico dentro del plan	Error
BR-002	No eliminar cuenta con movimientos	Error
BR-003	Solo cuentas de detalle aceptan movimientos	Error
BR-004	Tipo de cuenta no modificable si tiene movimientos	Error
BR-005	Balance de cuenta padre = suma de hijos	Info

---

Criterios de Aceptacion

• CRUD de planes de cuentas
• Estructura jerarquica ilimitada
• Templates predefinidos importables
• Validacion de codigos
• Calculo automatico de saldos
• No permitir eliminar cuentas con movimientos
• Exportar/importar plan en Excel

---

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	Requirements-Analyst	Creacion inicial