# EPICA: EPIC-RT-005 - Clientes y Programa de Lealtad

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-RT-005 |
| **Nombre** | Clientes y Programa de Lealtad |
| **Modulo** | clientes |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P1 (Alto) |
| **Estado** | Backlog |
| **Story Points** | 34 |
| **Sprint(s)** | Sprint 4-5 |

---

## Descripcion

Gestión de clientes y programa de fidelización. Registro de clientes, acumulación y canje de puntos, niveles de membresía, historial de compras y comunicación personalizada. Integración con POS para experiencia fluida en punto de venta.

---

## Objetivo de Negocio

- Aumentar frecuencia de compra
- Incrementar ticket promedio
- Reducir rotación de clientes
- Conocer mejor al cliente
- Marketing personalizado

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-RT005-001 | Como cajero, quiero registrar cliente rápidamente con datos mínimos | P0 | 3 | Backlog |
| US-RT005-002 | Como cajero, quiero buscar cliente por teléfono o email para asociar venta | P0 | 3 | Backlog |
| US-RT005-003 | Como cliente, quiero acumular puntos automáticamente por mis compras | P0 | 5 | Backlog |
| US-RT005-004 | Como cajero, quiero consultar puntos del cliente en el POS | P0 | 2 | Backlog |
| US-RT005-005 | Como cajero, quiero aplicar canje de puntos como descuento en venta | P0 | 5 | Backlog |
| US-RT005-006 | Como cliente, quiero ver mi historial de compras y puntos en app/web | P1 | 5 | Backlog |
| US-RT005-007 | Como marketing, quiero segmentar clientes por nivel de compra | P1 | 3 | Backlog |
| US-RT005-008 | Como marketing, quiero enviar promociones por email a segmentos | P1 | 3 | Backlog |
| US-RT005-009 | Como admin, quiero configurar reglas de acumulación de puntos | P0 | 3 | Backlog |
| US-RT005-010 | Como admin, quiero configurar niveles de membresía con beneficios | P2 | 2 | Backlog |

**Total Story Points:** 34 SP

---

## Programa de Puntos

```
┌─────────────────────────────────────────────────────────┐
│              PROGRAMA DE LEALTAD                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ACUMULACIÓN                                            │
│  ├── 1 punto por cada $10 de compra (configurable)      │
│  ├── Puntos extra en productos promocionales            │
│  ├── Bonificación por cumpleaños                        │
│  └── Multiplicadores por nivel                          │
│                                                         │
│  CANJE                                                  │
│  ├── 100 puntos = $10 de descuento (configurable)       │
│  ├── Mínimo de puntos para canjear                      │
│  ├── Máximo de descuento por transacción                │
│  └── Productos excluidos de canje                       │
│                                                         │
│  NIVELES DE MEMBRESÍA                                   │
│  ├── BRONCE: 0-999 puntos/año     → 1x puntos           │
│  ├── PLATA:  1000-4999 puntos/año → 1.5x puntos         │
│  ├── ORO:    5000+ puntos/año     → 2x puntos           │
│  └── Beneficios adicionales por nivel                   │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Flujo de Puntos en Venta

```
┌─────────────┐
│ BUSCAR CLI  │  ← Por teléfono o email
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ VER PUNTOS  │  ← Saldo disponible
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   VENTA     │  ← Agregar productos
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  ¿CANJEAR?  │ ─── Si ──► Aplicar descuento
└──────┬──────┘
       │ No
       ▼
┌─────────────┐
│    PAGO     │  ← Cerrar venta
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ + PUNTOS    │  ← Acumulación automática
└─────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Registro rápido de cliente
- [ ] Búsqueda por teléfono/email
- [ ] Acumulación automática de puntos
- [ ] Canje de puntos en POS
- [ ] Historial de cliente
- [ ] Niveles de membresía
- [ ] Segmentación de clientes
- [ ] Comunicación por email

**No Funcionales:**
- [ ] Búsqueda de cliente < 500ms
- [ ] Cálculo de puntos en tiempo real
- [ ] Historial de 3 años

**Tecnicos:**
- [ ] Integración con módulo POS
- [ ] Integración con e-commerce
- [ ] Servicio de email marketing
- [ ] API para app de cliente

---

## 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 | Integración de puntos |
| EPIC-RT-009 E-commerce | Cuenta de cliente |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `customers`
- [ ] Tablas: 7 (customers, points_transactions, membership_levels, segments, campaigns, communications, preferences)
- [ ] Funciones: 3 (calculate_points, apply_redemption, update_level)
- [ ] Indices: Por teléfono, email, nivel, puntos

**Backend:**
- [ ] Modulo: `customers`
- [ ] Entities: 6 (Customer, PointsTransaction, MembershipLevel, Segment, Campaign)
- [ ] Endpoints: 14
- [ ] Tests: 28

**Frontend:**
- [ ] Paginas: 5 (CustomerList, CustomerDetail, Segments, Campaigns, Config)
- [ ] Componentes: 12 (CustomerSearch, PointsDisplay, RedemptionModal, etc.)
- [ ] Stores: 1 (customersStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/customers | Crear cliente |
| GET | /api/customers/search | Buscar por teléfono/email |
| GET | /api/customers/:id | Detalle de cliente |
| GET | /api/customers/:id/points | Saldo de puntos |
| GET | /api/customers/:id/history | Historial de compras |
| POST | /api/customers/:id/earn | Acumular puntos |
| POST | /api/customers/:id/redeem | Canjear puntos |
| GET | /api/customers/segments | Listar segmentos |
| POST | /api/customers/campaigns | Crear campaña |
| POST | /api/customers/campaigns/:id/send | Enviar comunicación |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Fraude de puntos | Media | Alto | Auditoría + límites de canje |
| Clientes duplicados | Alta | Medio | Validación de teléfono/email |
| Baja adopción | Media | Medio | Capacitación a cajeros |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Reglas de puntos definidas
- [ ] Niveles de membresía aprobados

## Definition of Done (DoD)

- [ ] Programa de puntos funcionando
- [ ] Integración con POS operativa
- [ ] Niveles de membresía activos
- [ ] Segmentación de clientes
- [ ] 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