# US-MGN005-004: Gestionar Unidades de Medida

## Identificacion

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

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** gestionar unidades de medida y realizar conversiones entre ellas
**Para** manejar productos e inventarios con diferentes unidades

---

## Descripcion

El sistema debe permitir definir unidades de medida organizadas por categoria (peso, volumen, longitud, etc.) y establecer factores de conversion dentro de cada categoria. Cada tenant puede personalizar sus unidades.

### Contexto

- Categorias de unidades predefinidas
- Unidades base por categoria
- Factores de conversion configurables
- Usadas en productos e inventario

---

## Criterios de Aceptacion

### Escenario 1: Listar categorias de unidades

```gherkin
Given un usuario autenticado
When accede a GET /api/v1/catalogs/uom/categories
Then el sistema responde con status 200
  And retorna categorias: weight, volume, length, area, time, unit
  And cada categoria indica su unidad base
```

### Escenario 2: Listar unidades de una categoria

```gherkin
Given un usuario con permiso "catalogs.uom.read"
When accede a GET /api/v1/catalogs/uom?category=weight
Then retorna unidades de peso del tenant
  And cada unidad incluye: code, name, category, conversionFactor, isBase
  And kg (kilogramo) es la unidad base (factor 1)
```

### Escenario 3: Crear unidad de medida

```gherkin
Given un usuario con permiso "catalogs.uom.manage"
When envia POST /api/v1/catalogs/uom
  | code | "lb" |
  | name | "Libra" |
  | category | "weight" |
  | conversionFactor | 0.453592 |
Then el sistema responde con status 201
  And la unidad queda registrada
  And 1 lb = 0.453592 kg
```

### Escenario 4: Crear unidad base

```gherkin
Given una categoria sin unidad base definida
When envia POST con isBase: true
Then la unidad se crea con conversionFactor = 1
  And se marca como unidad base de la categoria
```

### Escenario 5: Convertir unidades

```gherkin
Given unidades definidas:
  | kg | factor 1.0 (base) |
  | lb | factor 0.453592 |
  | g  | factor 0.001 |
When envia POST /api/v1/catalogs/uom/convert
  | quantity | 10 |
  | fromUnit | "lb" |
  | toUnit | "kg" |
Then retorna:
  | originalQuantity | 10 |
  | convertedQuantity | 4.53592 |
  | fromUnit | "lb" |
  | toUnit | "kg" |
```

### Escenario 6: Conversion entre categorias diferentes

```gherkin
Given unidades de diferentes categorias
When intenta convertir de "kg" (weight) a "m" (length)
Then el sistema responde con status 400
  And el mensaje indica "No se pueden convertir unidades de diferentes categorias"
```

### Escenario 7: Eliminar unidad en uso

```gherkin
Given una unidad asignada a productos
When intenta eliminar la unidad
Then el sistema responde con status 409
  And el mensaje indica "Unidad en uso por N productos"
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  UNIDADES DE MEDIDA                           [+ Nueva Unidad]   |
+------------------------------------------------------------------+
| [Categoria: Todas v]  [Buscar...]                                |
+------------------------------------------------------------------+

PESO (Base: Kilogramo)
+------------------------------------------------------------------+
| CODIGO | NOMBRE        | FACTOR      | BASE | ACCIONES           |
+------------------------------------------------------------------+
| kg     | Kilogramo     | 1.0         | ✓    | [Editar]           |
| g      | Gramo         | 0.001       |      | [Editar] [Eliminar]|
| lb     | Libra         | 0.453592    |      | [Editar] [Eliminar]|
| oz     | Onza          | 0.0283495   |      | [Editar] [Eliminar]|
+------------------------------------------------------------------+

VOLUMEN (Base: Litro)
+------------------------------------------------------------------+
| l      | Litro         | 1.0         | ✓    | [Editar]           |
| ml     | Mililitro     | 0.001       |      | [Editar] [Eliminar]|
| gal    | Galon         | 3.78541     |      | [Editar] [Eliminar]|
+------------------------------------------------------------------+

CONVERTIDOR
+----------------------------------+
| Cantidad: [100     ]            |
| De:       [lb v]                |
| A:        [kg v]                |
| [=== Convertir ===]             |
|                                  |
| Resultado: 45.3592 kg           |
+----------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /catalogs/uom/categories | Listar categorias |
| GET | /catalogs/uom | Listar unidades |
| GET | /catalogs/uom/:code | Detalle unidad |
| POST | /catalogs/uom | Crear unidad |
| PATCH | /catalogs/uom/:code | Actualizar |
| DELETE | /catalogs/uom/:code | Eliminar |
| POST | /catalogs/uom/convert | Convertir |

### Formula de Conversion

```
convertedQty = originalQty * (fromUnit.factor / toUnit.factor)

Ejemplo: 10 lb a kg
= 10 * (0.453592 / 1.0) = 4.53592 kg
```

---

## Definicion de Done

- [ ] CRUD unidades de medida
- [ ] Categorias predefinidas con seed
- [ ] Funcion de conversion
- [ ] Validacion misma categoria
- [ ] Validacion referencias antes de eliminar
- [ ] Componente UomSelect
- [ ] Componente UomConverter
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla uom_categories | Categorias |
| Tabla uom | Unidades |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Productos | Unidad de medida |
| Inventario | Conversiones |

---

## Historial

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