# 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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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 |