# US-MGN010-001: Gestionar Plan de Cuentas

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN010-001 |
| **Modulo** | MGN-010 Financial |
| **Sprint** | Sprint 7 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 13 |
| **Estado** | Ready |
| **RF Relacionado** | RF-FIN-001 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** contador o administrador financiero
**Quiero** gestionar el plan de cuentas contables con estructura jerarquica
**Para** organizar la informacion financiera segun normativas contables

---

## Descripcion

El sistema permite crear y gestionar planes de cuentas con estructura jerarquica ilimitada. Soporta diferentes estandares contables (PCGA, NIIF) e incluye templates predefinidos importables. Los saldos se calculan automaticamente.

### Contexto

- Estructura jerarquica con LTREE
- Multiples niveles de detalle
- Templates predefinidos
- Calculo automatico de saldos

---

## Criterios de Aceptacion

### Escenario 1: Listar planes de cuentas

```gherkin
Given un administrador financiero
When accede a GET /api/v1/financial/charts
Then el sistema responde con status 200
  And retorna planes de cuentas del tenant
  And cada plan incluye cantidad de cuentas
```

### Escenario 2: Ver arbol de cuentas

```gherkin
Given un plan de cuentas existente
When consulta GET /api/v1/financial/charts/{id}/accounts?tree=true
Then retorna cuentas en estructura jerarquica
  And cada cuenta incluye sus hijos
  And muestra nivel en la jerarquia
```

### Escenario 3: Crear cuenta de grupo

```gherkin
Given plan de cuentas activo
When crea cuenta con isDetail = false
  | code | "1.1" |
  | name | "Activo Circulante" |
  | accountType | "asset" |
Then la cuenta se crea como cuenta de grupo
  And no permite movimientos directos
```

### Escenario 4: Crear cuenta de detalle

```gherkin
Given cuenta padre "1.1" existente
When crea cuenta con:
  | parentId | uuid de 1.1 |
  | code | "1.1.01.001" |
  | name | "Caja General" |
  | isDetail | true |
Then la cuenta se crea como cuenta de detalle
  And permite movimientos contables
```

### Escenario 5: Validar codigo unico

```gherkin
Given cuenta "1.1.01.001" existente
When intenta crear otra cuenta con mismo codigo
Then el sistema responde con status 400
  And indica "Codigo de cuenta duplicado"
```

### Escenario 6: No eliminar cuenta con movimientos

```gherkin
Given cuenta con asientos contables registrados
When intenta eliminar la cuenta
Then el sistema responde con status 400
  And indica "No se puede eliminar cuenta con movimientos"
```

### Escenario 7: Importar plan desde template

```gherkin
Given templates disponibles (PCGA_MX, NIIF_BASIC)
When importa POST /api/v1/financial/charts/import
  | template | "PCGA_MX" |
  | name | "Mi Plan 2025" |
Then se crea plan con cuentas del template
  And las cuentas mantienen estructura original
```

### Escenario 8: Consultar saldo de cuenta

```gherkin
Given cuenta con movimientos
When consulta GET /api/v1/financial/accounts/{id}/balance?periodId=uuid
Then retorna:
  | openingBalance | 50000 |
  | movements.debit | 100000 |
  | movements.credit | 80000 |
  | closingBalance | 70000 |
```

### Escenario 9: Buscar cuentas

```gherkin
Given multiples cuentas en el plan
When busca GET /api/v1/financial/charts/{id}/accounts?search=banco
Then retorna cuentas cuyo nombre o codigo contiene "banco"
```

### Escenario 10: Exportar plan a Excel

```gherkin
Given plan de cuentas completo
When exporta a Excel
Then genera archivo con columnas:
  | codigo, nombre, tipo, naturaleza, nivel, es_detalle |
  And mantiene estructura jerarquica visual
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  PLAN DE CUENTAS: PCGA 2025                         [+ Nueva Cuenta]|
+------------------------------------------------------------------+
| [Buscar...]  [Expandir todo] [Colapsar todo]  [Exportar]          |
+------------------------------------------------------------------+

| CODIGO       | NOMBRE                    | TIPO     | SALDO       |
+------------------------------------------------------------------+
| ▼ 1          | ACTIVO                    | Activo   | $1,200,000  |
|   ▼ 1.1      | Activo Circulante         | Activo   |   $500,000  |
|     ▼ 1.1.01 | Efectivo y Equivalentes   | Activo   |   $250,000  |
|       1.1.01.001 | Caja General          | Activo   |    $50,000  |
|       1.1.01.002 | Bancos                | Activo   |   $200,000  |
|     ▼ 1.1.02 | Cuentas por Cobrar        | Activo   |   $250,000  |
|       1.1.02.001 | Clientes Nacionales   | Activo   |   $180,000  |
|       1.1.02.002 | Clientes Extranjeros  | Activo   |    $70,000  |
|   ▼ 1.2      | Activo No Circulante      | Activo   |   $700,000  |
|     ...                                                            |
| ▼ 2          | PASIVO                    | Pasivo   |   $400,000  |
|   ...                                                              |
| ▼ 3          | CAPITAL                   | Capital  |   $800,000  |
|   ...                                                              |
+------------------------------------------------------------------+

Modal: Nueva Cuenta
+------------------------------------------------------------------+
| NUEVA CUENTA                                                 [X]  |
+------------------------------------------------------------------+
| Cuenta Padre                                                      |
| [1.1.01 - Efectivo y Equivalentes v]                             |
|                                                                   |
| Codigo*                                                           |
| [1.1.01.003                                                 ]    |
| Formato: X.X.XX.XXX (segun nivel)                                |
|                                                                   |
| Nombre*                                                           |
| [Fondo Fijo                                                 ]    |
|                                                                   |
| Tipo de Cuenta*                                                   |
| (•) Activo  ( ) Pasivo  ( ) Capital  ( ) Ingreso  ( ) Gasto      |
|                                                                   |
| Naturaleza*                                                       |
| (•) Deudora  ( ) Acreedora                                       |
|                                                                   |
| [✓] Cuenta de detalle (permite movimientos)                      |
|                                                                   |
| Moneda especifica (opcional)                                      |
| [Usar moneda base v]                                             |
|                                                                   |
|                              [Cancelar]  [=== Guardar ===]       |
+------------------------------------------------------------------+

Modal: Importar Template
+------------------------------------------------------------------+
| IMPORTAR PLAN DE CUENTAS                                    [X]  |
+------------------------------------------------------------------+
| Template*                                                         |
| [PCGA Mexico (500 cuentas) v]                                    |
|                                                                   |
| Nombre del Plan*                                                  |
| [Plan Contable 2025                                         ]    |
|                                                                   |
| Opciones                                                          |
| [ ] Solo importar grupos principales (niveles 1-2)               |
| [ ] Incluir descripciones                                         |
|                                                                   |
| Vista previa: 500 cuentas seran creadas                          |
|                                                                   |
|                              [Cancelar]  [=== Importar ===]      |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /financial/charts | Listar planes |
| POST | /financial/charts | Crear plan |
| GET | /financial/charts/:id | Detalle de plan |
| GET | /financial/charts/:id/accounts | Cuentas del plan |
| POST | /financial/charts/:id/accounts | Crear cuenta |
| PUT | /financial/accounts/:id | Actualizar cuenta |
| DELETE | /financial/accounts/:id | Eliminar cuenta |
| POST | /financial/charts/import | Importar template |
| GET | /financial/accounts/:id/balance | Saldo de cuenta |

### Estructura LTREE

```sql
-- Columna path para jerarquia
ALTER TABLE accounts ADD COLUMN path LTREE;

-- Indice para consultas jerarquicas
CREATE INDEX idx_accounts_path ON accounts USING GIST (path);

-- Ejemplo de paths:
-- 1 -> '1'
-- 1.1 -> '1.1'
-- 1.1.01 -> '1.1.01'
-- 1.1.01.001 -> '1.1.01.001'
```

### Tipos de Cuenta

| Tipo | Naturaleza | Uso |
|------|------------|-----|
| asset | debit | Activos |
| liability | credit | Pasivos |
| equity | credit | Capital |
| income | credit | Ingresos |
| expense | debit | Gastos |
| cost | debit | Costos |

---

## Definicion de Done

- [ ] CRUD de planes de cuentas
- [ ] Estructura jerarquica con LTREE
- [ ] Templates predefinidos importables
- [ ] Validacion de codigos unicos
- [ ] Calculo automatico de saldos
- [ ] No eliminar cuentas con movimientos
- [ ] Exportar a Excel
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla charts_of_accounts | Planes |
| Tabla accounts | Cuentas con LTREE |
| Extension ltree | Para jerarquias |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN010-004 | Asientos contables |
| Reportes financieros | Balance, Estado Resultados |

---

## Historial

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