# US-MGN010-002: Gestionar Monedas y Tipos de Cambio

## Identificacion

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

---

## Historia de Usuario

**Como** administrador financiero
**Quiero** gestionar multiples monedas y tipos de cambio
**Para** registrar operaciones en diferentes divisas con conversion automatica

---

## Descripcion

El sistema soporta operaciones multi-moneda con historial de tipos de cambio. Los usuarios pueden registrar tasas manualmente o sincronizar desde APIs externas. Todas las operaciones se convierten a moneda base automaticamente.

### Contexto

- Moneda base del tenant
- Historial de tipos de cambio
- Conversion automatica
- Integracion con APIs externas

---

## Criterios de Aceptacion

### Escenario 1: Listar monedas del tenant

```gherkin
Given un tenant con monedas configuradas
When consulta GET /api/v1/financial/currencies
Then retorna lista de monedas activas
  And indica cual es la moneda base
  And muestra tipo de cambio actual
```

### Escenario 2: Activar moneda

```gherkin
Given moneda "EUR" disponible pero inactiva
When activa la moneda para el tenant
Then la moneda queda disponible para transacciones
  And aparece en selectores de moneda
```

### Escenario 3: Registrar tipo de cambio

```gherkin
Given moneda USD activa
When registra POST /api/v1/financial/currencies/USD/rates
  | rate | 17.55 |
  | effectiveDate | "2025-12-05" |
Then el tipo de cambio se guarda
  And aplica a operaciones desde esa fecha
```

### Escenario 4: Consultar historial de tasas

```gherkin
Given tipos de cambio historicos
When consulta GET /api/v1/financial/currencies/USD/rates?from=2025-11-01&to=2025-12-05
Then retorna lista de tasas ordenadas por fecha
  And incluye source (manual, api)
```

### Escenario 5: Convertir monto

```gherkin
Given tipo de cambio USD/MXN = 17.50
When envia POST /api/v1/financial/currencies/convert
  | amount | 1000 |
  | from | "USD" |
  | to | "MXN" |
  | date | "2025-12-05" |
Then retorna:
  | convertedAmount | 17500 |
  | exchangeRate | 17.50 |
```

### Escenario 6: Tasa no existe para fecha

```gherkin
Given sin tipo de cambio para fecha especifica
When consulta conversion para esa fecha
Then usa el tipo de cambio mas reciente anterior
  And indica que es tasa aproximada
```

### Escenario 7: Configurar actualizacion automatica

```gherkin
Given tenant con API de Banxico configurada
When activa auto-update:
  | schedule | "0 8 * * 1-5" |
  | currencies | ["USD", "EUR"] |
Then el sistema actualiza tasas automaticamente
```

### Escenario 8: Sincronizar desde API externa

```gherkin
Given integracion con proveedor de tasas
When ejecuta sincronizacion
Then obtiene tasas actuales de la API
  And las registra con source = nombre del proveedor
```

### Escenario 9: Moneda base no modificable

```gherkin
Given tenant con movimientos registrados
When intenta cambiar moneda base
Then el sistema responde con error
  And indica que hay movimientos existentes
```

### Escenario 10: Formato por moneda

```gherkin
Given monedas con diferentes formatos
When muestra montos
Then aplica formato correcto:
  | MXN | $1,234.56 |
  | USD | US$1,234.56 |
  | EUR | €1.234,56 |
  | COP | $1.234 |
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  MONEDAS                                                          |
+------------------------------------------------------------------+
| [+ Activar Moneda]  [Sincronizar Tasas]                          |
+------------------------------------------------------------------+

MONEDAS ACTIVAS
+------------------------------------------------------------------+
| CODIGO | NOMBRE              | SIMBOLO | TC ACTUAL | ACCIONES    |
+------------------------------------------------------------------+
| MXN    | Peso Mexicano       | $       | 1.0000 ⭐  | [Configurar]|
| USD    | Dolar Estadounidense| US$     | 17.5000   | [Tasas][⚙] |
| EUR    | Euro                | €       | 19.2500   | [Tasas][⚙] |
+------------------------------------------------------------------+

⭐ = Moneda base

+------------------------------------------------------------------+
|  HISTORIAL DE TASAS - USD                          [+ Nueva Tasa] |
+------------------------------------------------------------------+
| [Desde: 2025-11-01]  [Hasta: 2025-12-05]  [Filtrar]              |
+------------------------------------------------------------------+

| FECHA        | TASA     | INVERSA  | FUENTE     |
+------------------------------------------------------------------+
| 2025-12-05   | 17.5500  | 0.0570   | Manual     |
| 2025-12-04   | 17.5000  | 0.0571   | Banxico    |
| 2025-12-03   | 17.4500  | 0.0573   | Banxico    |
| 2025-12-02   | 17.5200  | 0.0571   | Banxico    |
+------------------------------------------------------------------+

[GRAFICO: Tendencia del tipo de cambio]
    ^
18.0|     .
    |    / \
17.5|.../.  \.....
    |
17.0+----------------->
     Nov 1  Nov 15  Dic 1

Modal: Nueva Tasa de Cambio
+------------------------------------------------------------------+
| REGISTRAR TIPO DE CAMBIO                                    [X]  |
+------------------------------------------------------------------+
| Moneda: USD - Dolar Estadounidense                               |
| Moneda Base: MXN - Peso Mexicano                                 |
|                                                                   |
| Fecha Efectiva*                                                   |
| [2025-12-06      ] [📅]                                          |
|                                                                   |
| Tipo de Cambio*  (1 USD = ? MXN)                                 |
| [17.60                                                      ]    |
|                                                                   |
| Tasa Inversa: 0.0568                                             |
|                                                                   |
|                              [Cancelar]  [=== Guardar ===]       |
+------------------------------------------------------------------+

Modal: Configurar Actualizacion Automatica
+------------------------------------------------------------------+
| ACTUALIZACION AUTOMATICA DE TASAS                           [X]  |
+------------------------------------------------------------------+
| [✓] Activar actualizacion automatica                             |
|                                                                   |
| Proveedor                                                         |
| (•) Banxico (Mexico)                                             |
| ( ) BCE (Europa)                                                  |
| ( ) Open Exchange Rates (Global)                                 |
|                                                                   |
| Programacion                                                      |
| Frecuencia: [Diario v]  Hora: [08:00 v]                         |
| Dias: [✓ L] [✓ M] [✓ M] [✓ J] [✓ V] [ S] [ D]                   |
|                                                                   |
| Monedas a actualizar                                              |
| [✓] USD  [✓] EUR  [ ] GBP  [ ] JPY  [ ] CAD                     |
|                                                                   |
|                              [Cancelar]  [=== Guardar ===]       |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /financial/currencies | Listar monedas |
| POST | /financial/currencies/:code/activate | Activar moneda |
| DELETE | /financial/currencies/:code/deactivate | Desactivar |
| GET | /financial/currencies/:code/rates | Historial tasas |
| POST | /financial/currencies/:code/rates | Registrar tasa |
| POST | /financial/currencies/convert | Convertir monto |
| PUT | /financial/currencies/auto-update | Config auto |
| POST | /financial/currencies/sync | Sincronizar ahora |

### Proveedores de Tasas

| Proveedor | Endpoint | Monedas |
|-----------|----------|---------|
| Banxico | api.banxico.org.mx | MXN base |
| BCE | api.exchangeratesapi.io | EUR base |
| Open Exchange | openexchangerates.org | USD base |

### Precision Decimal

```typescript
// Usar Decimal.js para precision
import Decimal from 'decimal.js';

const rate = new Decimal('17.5543');
const amount = new Decimal('1000.00');
const converted = amount.times(rate).toDecimalPlaces(2);
```

---

## Definicion de Done

- [ ] CRUD de monedas
- [ ] Historial de tipos de cambio
- [ ] Conversion automatica
- [ ] Integracion con APIs externas
- [ ] Actualizacion programada
- [ ] Formato por moneda
- [ ] Grafico de tendencia
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla currencies | Catalogo base |
| Tabla tenant_currencies | Config por tenant |
| Tabla exchange_rates | Historial |
| Bull Queue | Para sincronizacion |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN010-004 | Asientos multi-moneda |
| Operaciones comerciales | Facturas en USD, etc |

---

## Historial

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