# EPICA: EPIC-RT-006 - Precios y Promociones

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-RT-006 |
| **Nombre** | Precios y Promociones |
| **Modulo** | precios |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 36 |
| **Sprint(s)** | Sprint 3-4 |

---

## Descripcion

Gestión de precios y promociones para retail. Listas de precios por sucursal/canal, promociones temporales, descuentos por volumen, cupones y ofertas especiales. Motor de reglas para aplicación automática en POS y e-commerce.

---

## Objetivo de Negocio

- Flexibilidad en estrategia de precios
- Promociones efectivas y controladas
- Incrementar ventas con ofertas
- Competir en diferentes canales
- Medir ROI de promociones

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-RT006-001 | Como pricing, quiero definir precio base de producto para tener referencia | P0 | 2 | Backlog |
| US-RT006-002 | Como pricing, quiero crear listas de precios por canal (tienda, online) | P0 | 5 | Backlog |
| US-RT006-003 | Como pricing, quiero crear promoción de descuento porcentual temporal | P0 | 5 | Backlog |
| US-RT006-004 | Como pricing, quiero crear promoción 2x1 o 3x2 para productos seleccionados | P0 | 5 | Backlog |
| US-RT006-005 | Como pricing, quiero crear descuento por volumen (> 10 unidades = 15% off) | P0 | 3 | Backlog |
| US-RT006-006 | Como marketing, quiero generar cupones de descuento con código único | P0 | 5 | Backlog |
| US-RT006-007 | Como cajero, quiero que el POS aplique promociones automáticamente | P0 | 5 | Backlog |
| US-RT006-008 | Como cajero, quiero escanear cupón para aplicar descuento | P0 | 3 | Backlog |
| US-RT006-009 | Como gerente, quiero ver reportes de uso de promociones | P1 | 3 | Backlog |

**Total Story Points:** 36 SP

---

## Tipos de Promociones

```
┌─────────────────────────────────────────────────────────┐
│              TIPOS DE PROMOCIONES                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  DESCUENTO PORCENTUAL                                   │
│  ├── Aplica X% de descuento                             │
│  ├── Sobre productos seleccionados o categoría          │
│  └── Período de vigencia                                │
│                                                         │
│  DESCUENTO MONTO FIJO                                   │
│  ├── Aplica $X de descuento                             │
│  ├── Requiere mínimo de compra                          │
│  └── Por producto o total de venta                      │
│                                                         │
│  NxM (ej: 3x2)                                          │
│  ├── Compra N productos, paga M                         │
│  ├── Mismo producto o mezcla                            │
│  └── El más barato gratis o porcentaje                  │
│                                                         │
│  DESCUENTO POR VOLUMEN                                  │
│  ├── Escalas de cantidad                                │
│  ├── > 5 unidades = 5% off                              │
│  └── > 10 unidades = 10% off                            │
│                                                         │
│  CUPÓN                                                  │
│  ├── Código único o genérico                            │
│  ├── Un uso o múltiples usos                            │
│  └── Límite de usos totales                             │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Motor de Reglas

```
┌─────────────────────────────────────────────────────────┐
│              EVALUACIÓN DE PRECIO                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. Obtener precio base del producto                    │
│                                                         │
│  2. Aplicar lista de precios del canal                  │
│     └── Si existe precio específico, usarlo             │
│                                                         │
│  3. Evaluar promociones activas                         │
│     ├── Ordenar por prioridad                           │
│     ├── Verificar condiciones (fechas, productos)       │
│     └── Aplicar la mejor promoción (no acumulables)     │
│                                                         │
│  4. Evaluar descuento por volumen                       │
│     └── Si cantidad supera umbral, aplicar              │
│                                                         │
│  5. Evaluar cupón (si se proporciona)                   │
│     ├── Validar código                                  │
│     ├── Verificar vigencia y usos                       │
│     └── Aplicar si es compatible                        │
│                                                         │
│  6. Retornar precio final con detalle de descuentos     │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Definir precio base de productos
- [ ] Crear listas de precios por canal
- [ ] Crear promociones temporales
- [ ] Promociones NxM
- [ ] Descuentos por volumen
- [ ] Generar y validar cupones
- [ ] Aplicación automática en POS
- [ ] Reportes de uso

**No Funcionales:**
- [ ] Cálculo de precio < 100ms
- [ ] Soporte para 100+ promociones activas
- [ ] Historial de 1 año de promociones

**Tecnicos:**
- [ ] Motor de reglas flexible
- [ ] Integración con POS
- [ ] Integración con e-commerce
- [ ] Cache de promociones activas

---

## Dependencias

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

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-RT-002 POS | Requiere precios para vender |
| EPIC-RT-009 E-commerce | Requiere precios online |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `pricing`
- [ ] Tablas: 8 (price_lists, prices, promotions, promotion_products, volume_discounts, coupons, coupon_usages, promo_logs)
- [ ] Funciones: 3 (calculate_price, validate_coupon, apply_promotion)
- [ ] Indices: Por producto, canal, fecha vigencia

**Backend:**
- [ ] Modulo: `pricing`
- [ ] Entities: 6 (PriceList, Price, Promotion, VolumeDiscount, Coupon, CouponUsage)
- [ ] Services: PricingEngine (motor de reglas)
- [ ] Endpoints: 15
- [ ] Tests: 35

**Frontend:**
- [ ] Paginas: 5 (PriceLists, Promotions, Coupons, Reports, Config)
- [ ] Componentes: 12 (PriceEditor, PromotionBuilder, CouponGenerator, etc.)
- [ ] Stores: 1 (pricingStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /api/pricing/products/:id | Obtener precio de producto |
| POST | /api/pricing/calculate | Calcular precio con promociones |
| GET | /api/pricing/lists | Listar listas de precios |
| POST | /api/pricing/lists | Crear lista de precios |
| GET | /api/pricing/promotions | Listar promociones |
| POST | /api/pricing/promotions | Crear promoción |
| PATCH | /api/pricing/promotions/:id | Actualizar promoción |
| POST | /api/pricing/coupons | Generar cupón |
| POST | /api/pricing/coupons/validate | Validar cupón |
| POST | /api/pricing/coupons/redeem | Usar cupón |
| GET | /api/pricing/reports/usage | Reporte de uso |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Promociones conflictivas | Media | Alto | Prioridades + no acumulable |
| Cupones fraudulentos | Baja | Medio | Códigos únicos + límites |
| Precios incorrectos | Media | Alto | Validación antes de activar |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Tipos de promociones definidos
- [ ] Reglas de compatibilidad claras

## Definition of Done (DoD)

- [ ] Motor de precios funcionando
- [ ] Promociones aplicándose en POS
- [ ] Cupones generándose y validándose
- [ ] Reportes de uso disponibles
- [ ] 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
