# US-MGN-005-001-002: Gestionar Variantes de Producto

**RF Asociado:** [RF-MGN-005-001](../../02-modelado/requerimientos-funcionales/mgn-005/RF-MGN-005-001-gestión-de-productos.md)
**Módulo:** MGN-005 - Inventario Básico
**Epic:** Gestión de Productos
**Prioridad:** P1
**Story Points:** 3
**Sprint:** Sprint 9
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story

**Como** usuario de inventario,
**Quiero** crear variantes de producto (ej: Laptop - Color: Negro, Tamaño: 15"),
**Para** gestionar productos con múltiples atributos y mantener stock separado por variante.

---

## Descripción Detallada

Las variantes de producto permiten gestionar productos que vienen en diferentes presentaciones. Por ejemplo, una camiseta puede tener variantes de color (blanco, negro, azul) y talla (S, M, L, XL). Cada variante es un producto independiente con su propio SKU y stock.

Las variantes se configuran a nivel de plantilla de producto (product_template) y se generan combinaciones automáticamente basadas en los atributos seleccionados.

---

## Criterios de Aceptación

### Escenario 1: Crear variantes de producto (Camino Feliz)
**Dado que** tengo un producto "Laptop",
**Cuando** configuro atributos: Color (Negro, Plata) y RAM (8GB, 16GB),
**Entonces** el sistema genera 4 variantes automáticamente con SKUs únicos.

### Escenario 2: Visualizar variantes de un producto
**Dado que** un producto tiene 4 variantes,
**Cuando** consulto el producto,
**Entonces** el sistema retorna la lista de variantes con sus atributos y stock.

### Escenario 3: Stock separado por variante
**Dado que** tengo variante "Laptop - Negro - 8GB" con stock 10,
**Cuando** consulto el stock,
**Entonces** el sistema muestra stock independiente por cada variante.

### Escenario 4: Validar atributos únicos
**Dado que** intento crear variante con combinación de atributos duplicada,
**Cuando** envío el request,
**Entonces** el sistema retorna error 400 "Combinación de atributos ya existe".

---

## Reglas de Negocio

- **RN-1:** Variantes son productos independientes con SKU único.
- **RN-2:** Variantes comparten plantilla de producto (product_template).
- **RN-3:** Stock se maneja por variante, no por plantilla.
- **RN-4:** Combinación de atributos debe ser única.
- **RN-5:** SKU de variante se genera automáticamente: [SKU_BASE]-[ATTR1]-[ATTR2].

---

## Tareas Técnicas

### Backend
- [ ] Endpoint: POST /api/v1/inventory/products/:id/variants
- [ ] Endpoint: GET /api/v1/inventory/products/:id/variants
- [ ] Service: ProductVariantService.create(productId, attributes)
- [ ] Service: ProductVariantService.generateVariants(productId, attributeCombinations)
- [ ] DTO: CreateVariantDto
- [ ] Validar atributos existen
- [ ] Generar SKU automático para variantes
- [ ] Unit tests (>80% coverage)
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Componente: ProductVariantsManager.tsx
- [ ] Componente: VariantAttributeSelector.tsx
- [ ] Tabla de variantes generadas
- [ ] API client: productApi.createVariants(id, data)
- [ ] Component tests
- [ ] E2E test: "should create product variants"

### Database
- [ ] Tabla: inventory.product_variants
- [ ] Tabla: inventory.product_attribute_values
- [ ] Índices: idx_variants_product_id
- [ ] RLS policy: company_isolation_variants

---

## Mockups / Wireframes

**Configurador de Variantes:**
```
┌─────────────────────────────────────────────┐
│ Variantes de Producto: Laptop             │
├─────────────────────────────────────────────┤
│ Atributos:                                  │
│ Color: [x] Negro [x] Plata [ ] Blanco      │
│ RAM: [x] 8GB [x] 16GB [ ] 32GB             │
│                                             │
│ [Generar Variantes]                        │
├─────────────────────────────────────────────┤
│ Variantes Generadas (4):                   │
│ ┌───────────────────────────────────────┐  │
│ │SKU         │Color │RAM  │Precio│Stock│  │
│ ├────────────┼──────┼─────┼──────┼─────┤  │
│ │PROD-001-BK-8│Negro │8GB  │800  │10   │  │
│ │PROD-001-BK-16│Negro│16GB │1000 │5    │  │
│ │PROD-001-SL-8│Plata │8GB  │850  │8    │  │
│ │PROD-001-SL-16│Plata│16GB │1050 │3    │  │
│ └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
```

---

## Casos de Prueba

### Funcionales
1. **TC-001:** Generar variantes automáticamente
2. **TC-002:** Stock separado por variante
3. **TC-003:** Error por combinación duplicada
4. **TC-004:** SKU automático generado correctamente

### No Funcionales
1. **Performance:** < 500ms para generar 10 variantes
2. **Seguridad:** JWT + permiso inventory_user

---

## Dependencias

- **US bloqueantes:** US-MGN-005-001-001 (Crear Producto)
- **Módulos requeridos:** MGN-003 (Atributos de Producto)
- **Datos maestros:** Atributos de producto

---

## Notas de Implementación

- Usar patrón Product Template + Product Variant (similar a Odoo)
- Frontend: Usar combinatorial logic para preview de variantes antes de crear
- Considerar límite máximo de variantes (ej: 100) para evitar explosión combinatoria

---

## Estimación Detallada

| Tarea | Horas |
|-------|-------|
| Backend | 1.5 |
| Frontend | 2 |
| Testing | 1 |
| Code Review | 0.5 |
| **TOTAL** | **5 horas = 3 SP** |

---

## Definition of Done

- [ ] Código implementado según ET
- [ ] Tests pasando (>80%)
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] QA validado
- [ ] PO aprobado

---

## Referencias

- [RF-MGN-005-001](../../02-modelado/requerimientos-funcionales/mgn-005/RF-MGN-005-001-gestión-de-productos.md)
- [ET Backend](../../02-modelado/especificaciones-tecnicas/backend/mgn-005/ET-BACKEND-MGN-005-001-gestión-de-productos.md)
- [ET Frontend](../../02-modelado/especificaciones-tecnicas/frontend/mgn-005/ET-FRONTEND-MGN-005-001-gestión-de-productos.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-005.yaml)
- [Schema](../../02-modelado/database-design/schemas/inventory-schema-ddl.sql)
