# US-MGN005-003: Gestionar Monedas y Tipos de Cambio

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN005-003 |
| **Modulo** | MGN-005 Catalogs |
| **Sprint** | Sprint 3 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 8 |
| **Estado** | Ready |
| **RF Relacionado** | RF-CATALOG-003 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador financiero
**Quiero** gestionar las monedas habilitadas y sus tipos de cambio
**Para** realizar operaciones multi-moneda con conversiones correctas

---

## Descripcion

El sistema debe permitir habilitar monedas para el tenant, definir una moneda base, y registrar tipos de cambio historicos. Las conversiones se realizan usando el tipo de cambio vigente a una fecha dada.

### Contexto

- Soporte multi-moneda por tenant
- Una moneda base obligatoria
- Tipos de cambio con fecha efectiva
- Conversion automatica en transacciones

---

## Criterios de Aceptacion

### Escenario 1: Listar monedas disponibles

```gherkin
Given un usuario autenticado
When accede a GET /api/v1/catalogs/currencies
Then el sistema responde con status 200
  And retorna catalogo global de monedas ISO 4217
  And cada moneda incluye: code, name, symbol, decimalPlaces
```

### Escenario 2: Ver monedas habilitadas del tenant

```gherkin
Given un usuario con permiso "catalogs.currencies.read"
When accede a GET /api/v1/catalogs/tenant-currencies
Then retorna solo monedas habilitadas para el tenant
  And indica cual es la moneda base (isBase: true)
  And muestra el tipo de cambio actual vs moneda base
```

### Escenario 3: Habilitar moneda para tenant

```gherkin
Given un usuario con permiso "catalogs.currencies.manage"
When envia POST /api/v1/catalogs/tenant-currencies
  | currencyCode | "EUR" |
  | isBase | false |
Then el sistema responde con status 201
  And la moneda EUR queda habilitada para el tenant
```

### Escenario 4: Definir moneda base

```gherkin
Given un tenant sin moneda base definida
  And un usuario con permiso "catalogs.currencies.manage"
When envia POST /api/v1/catalogs/tenant-currencies
  | currencyCode | "MXN" |
  | isBase | true |
Then MXN se establece como moneda base
  And todas las conversiones usaran MXN como referencia
```

### Escenario 5: Cambiar moneda base (no permitido)

```gherkin
Given un tenant con moneda base MXN
  And existen transacciones registradas
When intenta cambiar la moneda base a USD
Then el sistema responde con status 400
  And el mensaje indica "No se puede cambiar moneda base con transacciones existentes"
```

### Escenario 6: Registrar tipo de cambio

```gherkin
Given un usuario con permiso "catalogs.currencies.manage"
When envia POST /api/v1/catalogs/exchange-rates
  | fromCurrency | "USD" |
  | toCurrency | "MXN" |
  | rate | 17.25 |
  | effectiveDate | "2025-12-05" |
Then el sistema responde con status 201
  And el tipo de cambio queda registrado
```

### Escenario 7: Consultar tipo de cambio historico

```gherkin
Given tipos de cambio registrados para USD/MXN:
  | date | rate |
  | 2025-12-01 | 17.00 |
  | 2025-12-05 | 17.25 |
When consulta tipo de cambio para fecha 2025-12-03
Then retorna rate 17.00 (el vigente a esa fecha)
```

### Escenario 8: Convertir monto

```gherkin
Given tipo de cambio USD/MXN = 17.25 vigente
When envia POST /api/v1/catalogs/currencies/convert
  | amount | 100 |
  | from | "USD" |
  | to | "MXN" |
Then retorna:
  | originalAmount | 100 |
  | convertedAmount | 1725 |
  | rate | 17.25 |
```

### Escenario 9: Conversion sin tipo de cambio

```gherkin
Given no existe tipo de cambio para EUR/MXN
When intenta convertir de EUR a MXN
Then el sistema responde con status 404
  And el mensaje indica "Tipo de cambio no encontrado"
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  MONEDAS Y TIPOS DE CAMBIO                                        |
+------------------------------------------------------------------+

MONEDAS HABILITADAS
+------------------------------------------------------------------+
| CODIGO | NOMBRE           | SIMBOLO | BASE | TC ACTUAL           |
+------------------------------------------------------------------+
| MXN    | Peso Mexicano    | $       | ✓    | 1.0000              |
| USD    | Dolar USA        | $       |      | 17.2500             |
| EUR    | Euro             | €       |      | 18.5000             |
+------------------------------------------------------------------+
                                         [+ Habilitar Moneda]

TIPOS DE CAMBIO
+------------------------------------------------------------------+
| [Moneda: USD v]  [Fecha desde: ___] [Fecha hasta: ___] [Buscar] |
+------------------------------------------------------------------+
| FECHA       | DE   | A    | TASA    | FUENTE                     |
+------------------------------------------------------------------+
| 2025-12-05  | USD  | MXN  | 17.2500 | Manual                     |
| 2025-12-04  | USD  | MXN  | 17.2000 | Manual                     |
| 2025-12-03  | USD  | MXN  | 17.1500 | API Banco de Mexico        |
+------------------------------------------------------------------+
                                         [+ Nuevo Tipo de Cambio]

CONVERTIDOR
+----------------------------------+
| Monto: [1000    ]               |
| De:    [USD v]  A: [MXN v]      |
| Fecha: [2025-12-05]             |
| [=== Convertir ===]             |
|                                  |
| Resultado: $17,250.00 MXN       |
| Tasa: 1 USD = 17.25 MXN         |
+----------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /catalogs/currencies | Catalogo global |
| GET | /catalogs/tenant-currencies | Monedas del tenant |
| POST | /catalogs/tenant-currencies | Habilitar moneda |
| DELETE | /catalogs/tenant-currencies/:code | Deshabilitar |
| GET | /catalogs/exchange-rates | Listar tipos de cambio |
| POST | /catalogs/exchange-rates | Registrar tipo |
| GET | /catalogs/exchange-rates/current | Tipo actual |
| POST | /catalogs/currencies/convert | Convertir monto |

### Precision

- Tipos de cambio: DECIMAL(18,8)
- Montos: DECIMAL(18,4)
- Redondeo: HALF_UP segun decimales de moneda

---

## Definicion de Done

- [ ] CRUD monedas del tenant
- [ ] Registro de tipos de cambio
- [ ] Funcion de conversion
- [ ] Busqueda de tipo por fecha
- [ ] Validacion moneda base
- [ ] Componente CurrencySelect
- [ ] Componente CurrencyInput
- [ ] Tests unitarios
- [ ] Tests e2e
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla currencies | Catalogo ISO 4217 |
| Tabla tenant_currencies | Monedas habilitadas |
| Tabla exchange_rates | Tipos de cambio |

### Bloquea

| Item | Descripcion |
|------|-------------|
| MGN-010 Financial | Operaciones multi-moneda |
| Facturacion | Facturas en moneda extranjera |

---

## Historial

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