# US-MGN-006-005-002: Análisis de Desempeño de Proveedores

**RF Asociado:** [RF-MGN-006-006](../../02-modelado/requerimientos-funcionales/mgn-006/RF-MGN-006-006-reportes-de-compras.md)
**Módulo:** MGN-006 - Compras Básico
**Epic:** Reportes de Compras
**Prioridad:** P1
**Story Points:** 2
**Sprint:** Sprint 15
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story
**Como** gerente de compras,
**Quiero** analizar el desempeño de proveedores,
**Para** evaluar calidad, puntualidad y costos.

---

## Descripción Detallada
Reporte muestra por proveedor:
- Total de compras (monto)
- Cantidad de PO
- Tasa de entregas a tiempo (%)
- Tasa de devoluciones (%)
- Precio promedio vs competencia
- Rating/calificación

Exportable a Excel para análisis detallado.

---

## Criterios de Aceptación

### Escenario 1: Ver análisis de proveedores (Camino Feliz)
**Dado que** hay múltiples proveedores con PO,
**Cuando** genero reporte,
**Entonces** veo tabla con: proveedor, monto total, #PO, % entregas a tiempo, % devoluciones.

### Escenario 2: Filtrar por período
**Dado que** filtro por último trimestre,
**Cuando** aplico filtro,
**Entonces** reporte muestra solo datos de ese período.

### Escenario 3: Exportar a Excel
**Dado que** visualizo reporte,
**Cuando** exporto,
**Entonces** descargo archivo Excel con todos los datos.

---

## Reglas de Negocio
- **RN-1:** Entregas a tiempo = recepciones validadas antes de fecha esperada.
- **RN-2:** Tasa devolución = (unidades devueltas / unidades recibidas) × 100.
- **RN-3:** Exportable a Excel.

---

## Tareas Técnicas

### Backend
- [ ] Endpoint: GET /api/v1/purchase/reports/supplier-analysis
- [ ] Service: PurchaseReportService.getSupplierAnalysis(filters)
- [ ] Calcular métricas por proveedor
- [ ] Export service (Excel)
- [ ] Unit tests
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Página: SupplierAnalysisPage.tsx
- [ ] Tabla con ordenamiento por columna
- [ ] Filtros: fecha, categoría proveedor
- [ ] Botón exportar Excel
- [ ] API client: purchaseReportApi
- [ ] Component tests
- [ ] E2E test

### Database
- [ ] View: vw_supplier_performance
- [ ] Índices optimizados

---

## Estimación Detallada
| Tarea | Horas |
|-------|-------|
| Backend | 1.5 |
| Frontend | 1.5 |
| Testing | 0.5 |
| Code Review | 0.5 |
| **TOTAL** | **4 horas = 2 SP** |

---

## Definition of Done
- [ ] Código implementado según ET
- [ ] Tests pasando (>80%)
- [ ] Code review aprobado
- [ ] Métricas correctas
- [ ] Exportación funciona
- [ ] QA validado
- [ ] PO aprobado

---

## Referencias
- [RF-MGN-006-006](../../02-modelado/requerimientos-funcionales/mgn-006/RF-MGN-006-006-reportes-de-compras.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-006.yaml)