# US-MGN005-002: Consultar Paises y Estados

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN005-002 |
| **Modulo** | MGN-005 Catalogs |
| **Sprint** | Sprint 3 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 3 |
| **Estado** | Ready |
| **RF Relacionado** | RF-CATALOG-002 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** consultar catalogos de paises y estados/provincias
**Para** seleccionar ubicaciones geograficas al capturar direcciones

---

## Descripcion

El sistema debe proporcionar catalogos globales de paises (ISO 3166-1) y estados/provincias por pais. Estos catalogos son de solo lectura para usuarios y se usan en formularios de direccion.

### Contexto

- Catalogos globales compartidos entre tenants
- Basados en estandares ISO
- Usados en direcciones de contactos
- Incluyen agrupaciones regionales

---

## Criterios de Aceptacion

### Escenario 1: Listar paises

```gherkin
Given un usuario autenticado
When accede a GET /api/v1/catalogs/countries
Then el sistema responde con status 200
  And retorna lista de paises ordenados por nombre
  And cada pais incluye: code (ISO), name, dialCode, currencyCode
  And los paises inactivos no se incluyen
```

### Escenario 2: Buscar paises

```gherkin
Given un usuario autenticado
When envia GET /api/v1/catalogs/countries?search=mex
Then retorna paises cuyo nombre o codigo contengan "mex"
  And Mexico aparece en los resultados

When envia GET /api/v1/catalogs/countries?region=latam
Then retorna solo paises del grupo "latam"
```

### Escenario 3: Obtener estados de un pais

```gherkin
Given un usuario autenticado
When envia GET /api/v1/catalogs/countries/MX/states
Then el sistema responde con status 200
  And retorna lista de estados de Mexico
  And cada estado incluye: code, name, countryCode
  And ordenados alfabeticamente por nombre
```

### Escenario 4: Pais sin estados

```gherkin
Given un pais pequeno sin subdivision administrativa
When envia GET /api/v1/catalogs/countries/MC/states
Then el sistema responde con status 200
  And retorna array vacio
```

### Escenario 5: Pais no encontrado

```gherkin
Given un codigo de pais que no existe "XX"
When envia GET /api/v1/catalogs/countries/XX
Then el sistema responde con status 404
  And el mensaje indica "Pais no encontrado"
```

### Escenario 6: Listar grupos regionales

```gherkin
Given un usuario autenticado
When envia GET /api/v1/catalogs/country-groups
Then retorna grupos como: latam, europe, nafta, asia
  And cada grupo incluye: code, name, countries[]
```

---

## Mockup / Wireframe

```
Selector de Pais (Dropdown con busqueda)
+----------------------------------+
| Pais *                           |
| [🔍 Buscar pais...          v]  |
+----------------------------------+
| 🇲🇽 Mexico                       |
| 🇺🇸 Estados Unidos               |
| 🇪🇸 Espana                       |
| 🇦🇷 Argentina                    |
| ...                              |
+----------------------------------+

Selector de Estado (Dependiente del pais)
+----------------------------------+
| Estado *                         |
| [Selecciona estado...       v]  |
+----------------------------------+
| Aguascalientes                   |
| Baja California                  |
| Baja California Sur              |
| Campeche                         |
| ...                              |
+----------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /catalogs/countries | Listar paises |
| GET | /catalogs/countries/:code | Detalle de pais |
| GET | /catalogs/countries/:code/states | Estados del pais |
| GET | /catalogs/country-groups | Listar grupos |

### Cache

- Catalogos se cachean en Redis por 24 horas
- Cache key: `catalogs:countries`, `catalogs:countries:MX:states`
- Invalidacion manual por admin

### Datos ISO

- Paises: ISO 3166-1 alpha-2
- Estados: ISO 3166-2

---

## Definicion de Done

- [ ] Endpoints de consulta implementados
- [ ] Datos seed de paises y estados cargados
- [ ] Cache Redis configurado
- [ ] Componente CountrySelect implementado
- [ ] Componente StateSelect (dependiente) implementado
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla countries | Con datos ISO 3166-1 |
| Tabla states | Con datos ISO 3166-2 |
| Redis | Para cache |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN005-001 | Direcciones de contactos |
| Cualquier formulario | Con seleccion de ubicacion |

---

## Historial

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