# US-MGN-005-006-002: Valoración de Inventario Promedio

**RF Asociado:** [RF-MGN-005-006](../../02-modelado/requerimientos-funcionales/mgn-005/RF-MGN-005-006-valoración-de-inventario-fifo,-promedio.md)
**Módulo:** MGN-005 - Inventario Básico
**Epic:** Valoración de Inventario
**Prioridad:** P0
**Story Points:** 5
**Sprint:** Sprint 11
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story
**Como** usuario financiero,
**Quiero** que el sistema calcule la valoración de inventario usando método Promedio Ponderado,
**Para** simplificar la contabilidad y conocer el costo promedio del stock.

---

## Descripción Detallada
El método Promedio Ponderado calcula un costo unitario promedio que se actualiza con cada entrada:

Nuevo Costo Promedio = (Valor Stock Actual + Valor Entrada) / (Cantidad Actual + Cantidad Entrada)

Al consumir stock, se usa el costo promedio actual. No se mantienen capas separadas como en FIFO.

---

## Criterios de Aceptación

### Escenario 1: Calcular costo promedio en entrada (Camino Feliz)
**Dado que** tengo stock: qty=10, avg_cost=100 (valor=1000), recibo 5 unidades a cost=120 (valor=600),
**Cuando** valido la entrada,
**Entonces** el sistema calcula: nuevo_avg_cost = (1000+600)/(10+5) = 106.67, qty=15.

### Escenario 2: Consumir stock con costo promedio
**Dado que** stock tiene qty=15, avg_cost=106.67,
**Cuando** consumo 5 unidades,
**Entonces** el sistema valora salida en 5×106.67=533.35, queda qty=10, avg_cost=106.67.

### Escenario 3: Recalcular costo promedio tras múltiples movimientos
**Dado que** hay múltiples entradas y salidas,
**Cuando** consulto costo promedio actual,
**Entonces** el sistema retorna el avg_cost actualizado del producto.

---

## Reglas de Negocio
- **RN-1:** Costo promedio se recalcula con cada entrada.
- **RN-2:** Salidas usan el costo promedio actual.
- **RN-3:** No se mantienen capas de valoración (simplificado vs FIFO).
- **RN-4:** Costo promedio se guarda en inventory.products.standard_price.

---

## Tareas Técnicas

### Backend
- [ ] Service: ValuationService.calculateAverageCost(product, entry)
- [ ] Service: ValuationService.updateAverageCost(productId, newCost)
- [ ] Service: ValuationService.valueExitAverage(product, quantity)
- [ ] Algoritmo costo promedio ponderado
- [ ] Unit tests (>80%)
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Componente: AverageCostReport.tsx
- [ ] Gráfico evolución de costo promedio
- [ ] API client: valuationApi
- [ ] Component tests
- [ ] E2E test

### Database
- [ ] Campo: inventory.products.standard_price (costo promedio actual)
- [ ] Índices: idx_products_company_id
- [ ] Trigger: actualizar standard_price en movimientos

---

## Estimación Detallada
| Tarea | Horas |
|-------|-------|
| Backend | 3 |
| Frontend | 2.5 |
| Testing | 2 |
| Code Review | 0.5 |
| **TOTAL** | **8 horas = 5 SP** |

---

## Definition of Done
- [ ] Código implementado según ET
- [ ] Tests pasando (>80%)
- [ ] Code review aprobado
- [ ] Algoritmo promedio correcto
- [ ] QA validado
- [ ] PO aprobado

---

## Referencias
- [RF-MGN-005-006](../../02-modelado/requerimientos-funcionales/mgn-005/RF-MGN-005-006-valoración-de-inventario-fifo,-promedio.md)
- [ET Backend](../../02-modelado/especificaciones-tecnicas/backend/mgn-005/ET-BACKEND-MGN-005-006-valoración-de-inventario-fifo-promedio.md)
- [ET Frontend](../../02-modelado/especificaciones-tecnicas/frontend/mgn-005/ET-FRONTEND-MGN-005-006-valoración-de-inventario-fifo-promedio.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-005.yaml)
- [Schema](../../02-modelado/database-design/schemas/inventory-schema-ddl.sql)