# EPICA: EPIC-RT-004 - Compras y Reabastecimiento

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-RT-004 |
| **Nombre** | Compras y Reabastecimiento |
| **Modulo** | compras |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 38 |
| **Sprint(s)** | Sprint 5-6 |

---

## Descripcion

Gestión de compras a proveedores para reabastecimiento de tiendas. Incluye sugerencias automáticas de compra basadas en stock mínimo, gestión de órdenes de compra, recepción de mercancía y evaluación de proveedores.

---

## Objetivo de Negocio

- Evitar quiebres de stock
- Optimizar niveles de inventario
- Negociar mejores condiciones con proveedores
- Automatizar proceso de reabastecimiento
- Control de costos de compra

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-RT004-001 | Como comprador, quiero ver sugerencias de compra basadas en stock mínimo | P0 | 5 | Backlog |
| US-RT004-002 | Como comprador, quiero crear orden de compra desde sugerencias | P0 | 5 | Backlog |
| US-RT004-003 | Como comprador, quiero agregar productos manualmente a orden de compra | P0 | 3 | Backlog |
| US-RT004-004 | Como comprador, quiero enviar orden de compra al proveedor por email | P0 | 3 | Backlog |
| US-RT004-005 | Como almacenista, quiero recibir mercancía validando contra orden de compra | P0 | 5 | Backlog |
| US-RT004-006 | Como almacenista, quiero registrar diferencias en recepción (faltantes/sobrantes) | P0 | 3 | Backlog |
| US-RT004-007 | Como comprador, quiero gestionar catálogo de proveedores con datos de contacto | P0 | 3 | Backlog |
| US-RT004-008 | Como comprador, quiero ver historial de compras por proveedor | P1 | 3 | Backlog |
| US-RT004-009 | Como gerente, quiero ver métricas de cumplimiento de proveedores | P1 | 5 | Backlog |
| US-RT004-010 | Como admin, quiero configurar lead times por proveedor para sugerencias | P2 | 3 | Backlog |

**Total Story Points:** 38 SP

---

## Flujo de Orden de Compra

```
┌─────────────┐
│  BORRADOR   │  ← OC siendo creada
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  CONFIRMADA │  ← Aprobada internamente
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   ENVIADA   │  ← Enviada al proveedor
└──────┬──────┘
       │
       ├──────────────┐
       ▼              ▼
┌─────────────┐ ┌─────────────┐
│ RECIB_PARC  │ │   RECIBIDA  │
│  (parcial)  │ │  (completa) │
└──────┬──────┘ └──────┬──────┘
       │               │
       ▼               ▼
┌─────────────────────────┐
│        CERRADA          │
└─────────────────────────┘
```

---

## Algoritmo de Sugerencias

```
┌─────────────────────────────────────────────────────────┐
│              CÁLCULO DE SUGERENCIA DE COMPRA            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  PARA CADA PRODUCTO:                                    │
│                                                         │
│  stock_actual = consultar_stock(producto, sucursal)     │
│  stock_minimo = producto.stock_minimo                   │
│  stock_maximo = producto.stock_maximo                   │
│  ventas_diarias = promedio_ventas(producto, 30_dias)    │
│  lead_time = proveedor.lead_time_dias                   │
│                                                         │
│  punto_reorden = stock_minimo + (ventas_diarias * lead_time)
│                                                         │
│  SI stock_actual <= punto_reorden:                      │
│     cantidad_sugerida = stock_maximo - stock_actual     │
│     CREAR_SUGERENCIA(producto, cantidad_sugerida)       │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Sugerencias automáticas de compra
- [ ] Crear OC desde sugerencias
- [ ] Agregar productos manualmente
- [ ] Enviar OC por email
- [ ] Recibir mercancía con validación
- [ ] Registrar diferencias
- [ ] Catálogo de proveedores
- [ ] Métricas de cumplimiento

**No Funcionales:**
- [ ] Cálculo de sugerencias < 30 segundos (todos los productos)
- [ ] Historial de 2 años de OC
- [ ] Soporte para 50+ proveedores

**Tecnicos:**
- [ ] Integración con módulo Inventario
- [ ] Envío de emails con PDF adjunto
- [ ] Job programado para sugerencias

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-RT-001 Fundamentos | Backlog | Si |
| EPIC-RT-003 Inventario | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-RT-003 Inventario | Recepciones actualizan stock |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `purchases`
- [ ] Tablas: 7 (purchase_orders, po_items, suppliers, supplier_products, receipts, receipt_items, suggestions)
- [ ] Funciones: 3 (calculate_suggestions, validate_receipt, evaluate_supplier)
- [ ] Indices: Por proveedor, fecha, estado

**Backend:**
- [ ] Modulo: `purchases`
- [ ] Entities: 6 (PurchaseOrder, POItem, Supplier, SupplierProduct, Receipt, Suggestion)
- [ ] Endpoints: 15
- [ ] Tests: 30

**Frontend:**
- [ ] Paginas: 5 (Suggestions, PurchaseOrders, PODetail, Suppliers, Receipts)
- [ ] Componentes: 12 (SuggestionCard, POForm, SupplierSelector, ReceiptValidator, etc.)
- [ ] Stores: 1 (purchasesStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /api/purchases/suggestions | Ver sugerencias de compra |
| POST | /api/purchases/orders | Crear orden de compra |
| GET | /api/purchases/orders/:id | Detalle de OC |
| PATCH | /api/purchases/orders/:id | Actualizar OC |
| POST | /api/purchases/orders/:id/send | Enviar a proveedor |
| POST | /api/purchases/receipts | Registrar recepción |
| GET | /api/purchases/suppliers | Listar proveedores |
| POST | /api/purchases/suppliers | Crear proveedor |
| GET | /api/purchases/suppliers/:id/metrics | Métricas de proveedor |
| POST | /api/purchases/calculate-suggestions | Recalcular sugerencias |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Sugerencias incorrectas | Media | Alto | Validación manual antes de OC |
| Proveedor no cumple | Media | Alto | Proveedores alternativos |
| Recepciones incompletas | Media | Medio | Flujo de diferencias |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Catálogo inicial de proveedores
- [ ] Lead times definidos

## Definition of Done (DoD)

- [ ] Sugerencias de compra funcionando
- [ ] Flujo completo de OC operativo
- [ ] Recepción con validación
- [ ] Métricas de proveedores
- [ ] Tests de integración pasando
- [ ] Documentación de API

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-08 | Creacion de epica | Claude-Agent |

---

**Creada por:** Claude-Agent
**Fecha:** 2025-12-08
**Ultima actualizacion:** 2025-12-08