# US-MGN010-003: Gestionar Periodos Contables

## Identificacion

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

---

## Historia de Usuario

**Como** contador
**Quiero** gestionar años fiscales y periodos contables
**Para** controlar el cierre de periodos y restringir movimientos fuera de fechas permitidas

---

## Descripcion

El sistema gestiona años fiscales con periodos mensuales (u otros). Controla apertura/cierre de periodos, valida fechas de contabilizacion y ejecuta procesos de cierre que generan saldos y asientos de cierre.

### Contexto

- Años fiscales con periodos
- Control de fechas de contabilizacion
- Proceso de cierre de periodo
- Cierre anual con asientos automaticos

---

## Criterios de Aceptacion

### Escenario 1: Listar años fiscales

```gherkin
Given años fiscales existentes
When consulta GET /api/v1/financial/fiscal-years
Then retorna lista de años con:
  | name, startDate, endDate, status, openPeriodsCount |
```

### Escenario 2: Crear año fiscal

```gherkin
Given necesidad de nuevo año
When crea POST /api/v1/financial/fiscal-years
  | name | "Ejercicio 2026" |
  | startDate | "2026-01-01" |
  | endDate | "2026-12-31" |
  | periodType | "monthly" |
Then se crea el año con 12 periodos automaticamente
  And los periodos tienen status = "future"
```

### Escenario 3: Ver periodos del año

```gherkin
Given año fiscal 2025
When consulta GET /api/v1/financial/fiscal-years/{id}/periods
Then retorna lista de 12 periodos:
  | Enero: closed, Febrero: closed, ..., Diciembre: open |
```

### Escenario 4: Abrir periodo

```gherkin
Given periodo con status = "future"
When ejecuta POST /api/v1/financial/periods/{id}/open
Then el periodo cambia a status = "open"
  And permite movimientos contables
```

### Escenario 5: Validar fecha de contabilizacion

```gherkin
Given periodo Noviembre cerrado
When intenta registrar asiento con fecha en Noviembre
Then el sistema rechaza el movimiento
  And indica "Periodo cerrado para contabilizacion"
```

### Escenario 6: Cerrar periodo

```gherkin
Given periodo abierto con movimientos cuadrados
When ejecuta POST /api/v1/financial/periods/{id}/close
Then el sistema:
  | Valida que saldos cuadran |
  | Calcula saldos de cierre |
  | Cambia status a "closed" |
```

### Escenario 7: Cerrar periodo con advertencias

```gherkin
Given periodo con documentos pendientes
When intenta cerrar
Then el sistema muestra advertencias:
  | "5 facturas sin contabilizar" |
  And permite continuar o cancelar
```

### Escenario 8: Reabrir periodo (excepcion)

```gherkin
Given periodo cerrado
  And usuario con permiso especial
When ejecuta POST /api/v1/financial/periods/{id}/reopen
  | reason | "Correccion de asiento" |
Then el periodo se reabre temporalmente
  And se registra en audit log
```

### Escenario 9: Cierre de año fiscal

```gherkin
Given todos los periodos del año cerrados
When ejecuta POST /api/v1/financial/fiscal-years/{id}/close
Then el sistema:
  | Genera asiento de cierre (P&L -> Utilidades) |
  | Calcula saldos iniciales para nuevo año |
  | Crea asiento de apertura en nuevo año |
  | Marca año como "closed" |
```

### Escenario 10: Periodo de ajuste

```gherkin
Given año fiscal con periodo de ajuste habilitado
When consulta periodos
Then existe periodo 13 "Ajustes"
  And solo permite asientos de ajuste
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  AÑOS FISCALES                                    [+ Nuevo Año]   |
+------------------------------------------------------------------+

| AÑO          | INICIO     | FIN        | PERIODOS | ESTADO       |
+------------------------------------------------------------------+
| Ejercicio 2025| 2025-01-01 | 2025-12-31 | 11/12    | ✓ Abierto    |
| Ejercicio 2024| 2024-01-01 | 2024-12-31 | 12/12    | 🔒 Cerrado   |
| Ejercicio 2023| 2023-01-01 | 2023-12-31 | 12/12    | 🔒 Cerrado   |
+------------------------------------------------------------------+

+------------------------------------------------------------------+
|  PERIODOS - EJERCICIO 2025                                        |
+------------------------------------------------------------------+

| # | PERIODO       | INICIO     | FIN        | ESTADO    | ACCIONES |
+------------------------------------------------------------------+
| 1 | Enero 2025    | 2025-01-01 | 2025-01-31 | 🔒 Cerrado |          |
| 2 | Febrero 2025  | 2025-02-01 | 2025-02-28 | 🔒 Cerrado |          |
| 3 | Marzo 2025    | 2025-03-01 | 2025-03-31 | 🔒 Cerrado |          |
| 4 | Abril 2025    | 2025-04-01 | 2025-04-30 | 🔒 Cerrado |          |
| 5 | Mayo 2025     | 2025-05-01 | 2025-05-31 | 🔒 Cerrado |          |
| 6 | Junio 2025    | 2025-06-01 | 2025-06-30 | 🔒 Cerrado |          |
| 7 | Julio 2025    | 2025-07-01 | 2025-07-31 | 🔒 Cerrado |          |
| 8 | Agosto 2025   | 2025-08-01 | 2025-08-31 | 🔒 Cerrado |          |
| 9 | Septiembre 2025| 2025-09-01| 2025-09-30 | 🔒 Cerrado |          |
| 10| Octubre 2025  | 2025-10-01 | 2025-10-31 | 🔒 Cerrado |          |
| 11| Noviembre 2025| 2025-11-01 | 2025-11-30 | 🔒 Cerrado |[Reabrir] |
| 12| Diciembre 2025| 2025-12-01 | 2025-12-31 | ✓ Abierto | [Cerrar] |
+------------------------------------------------------------------+

Modal: Cerrar Periodo
+------------------------------------------------------------------+
| CERRAR PERIODO: Diciembre 2025                              [X]  |
+------------------------------------------------------------------+
| Validaciones previas al cierre:                                   |
|                                                                   |
| [✓] Todos los asientos cuadrados                                 |
| [✓] Saldos de cuentas verificados                                |
| [⚠] 3 facturas pendientes de contabilizar (no obligatorio)       |
|                                                                   |
| Resumen de periodo:                                               |
| - Total asientos: 245                                             |
| - Total debe: $5,234,567.00                                       |
| - Total haber: $5,234,567.00                                      |
| - Diferencia: $0.00                                               |
|                                                                   |
| [✓] Generar saldos de cierre                                     |
| [✓] Notificar a contadores                                       |
|                                                                   |
|                [Cancelar]  [=== Cerrar Periodo ===]              |
+------------------------------------------------------------------+

Modal: Cierre de Año
+------------------------------------------------------------------+
| CIERRE DEL EJERCICIO 2025                                   [X]  |
+------------------------------------------------------------------+
| Este proceso realizara:                                           |
|                                                                   |
| 1. Cierre de cuentas de resultados                               |
|    - Ingresos -> $8,500,000                                       |
|    - Gastos -> $6,200,000                                         |
|    - Resultado del ejercicio -> $2,300,000                       |
|                                                                   |
| 2. Traspaso a utilidades acumuladas                              |
|    - Cuenta: 3.4.01 - Utilidades Acumuladas                      |
|                                                                   |
| 3. Generacion de saldos iniciales 2026                           |
|    - Se crearan 156 saldos iniciales                             |
|                                                                   |
| [✓] Crear nuevo ejercicio 2026 automaticamente                   |
|                                                                   |
| ⚠️ Este proceso no puede revertirse                              |
|                                                                   |
|                [Cancelar]  [=== Cerrar Ejercicio ===]            |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /financial/fiscal-years | Listar años |
| POST | /financial/fiscal-years | Crear año |
| GET | /financial/fiscal-years/:id | Detalle de año |
| GET | /financial/fiscal-years/:id/periods | Periodos |
| POST | /financial/periods/:id/open | Abrir periodo |
| POST | /financial/periods/:id/close | Cerrar periodo |
| POST | /financial/periods/:id/reopen | Reabrir |
| POST | /financial/fiscal-years/:id/close | Cierre anual |

### Proceso de Cierre

```typescript
async function closePeriod(periodId: UUID): Promise<CloseResult> {
  await this.validateBalances(periodId);
  await this.checkPendingDocs(periodId);
  await this.calculateClosingBalances(periodId);
  await this.updatePeriodStatus(periodId, 'closed');
  await this.notifyAccountants(periodId);
  return { success: true };
}
```

### Validaciones

| Validacion | Obligatoria | Descripcion |
|------------|-------------|-------------|
| Saldos cuadrados | Si | Debe = Haber |
| Docs pendientes | No | Advertencia |
| Asientos en borrador | No | Advertencia |

---

## Definicion de Done

- [ ] CRUD de años fiscales
- [ ] Generacion automatica de periodos
- [ ] Control de fechas de contabilizacion
- [ ] Proceso de cierre de periodo
- [ ] Proceso de cierre de año
- [ ] Generacion de saldos iniciales
- [ ] Reabrir con autorizacion
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla fiscal_years | Años fiscales |
| Tabla fiscal_periods | Periodos |
| US-MGN010-001 | Plan de cuentas |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN010-004 | Asientos (valida periodo) |
| Reportes | Balance, Estado Resultados |

---

## Historial

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