erp-retail/docs/08-epicas/EPIC-RT-002-pos.md

# EPICA: EPIC-RT-002 - Punto de Venta (POS)

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-RT-002 |
| **Nombre** | Punto de Venta (POS) |
| **Modulo** | pos |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 55 |
| **Sprint(s)** | Sprint 2-4 |

---

## Descripcion

Sistema de punto de venta optimizado para retail. PWA que funciona offline, permite ventas rápidas con escaneo de código de barras, múltiples formas de pago, integración con programa de lealtad y sincronización automática con inventario central.

---

## Objetivo de Negocio

- Ventas rápidas (< 30 segundos por transacción)
- Operación sin interrupciones (offline)
- Control en tiempo real de ventas
- Experiencia fluida para cajeros
- Integración omnicanal

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-RT002-001 | Como cajero, quiero escanear código de barras para agregar productos rápidamente | P0 | 5 | Backlog |
| US-RT002-002 | Como cajero, quiero buscar producto por nombre si no tiene código de barras | P0 | 3 | Backlog |
| US-RT002-003 | Como cajero, quiero ver carrito de compra con totales en tiempo real | P0 | 3 | Backlog |
| US-RT002-004 | Como cajero, quiero aplicar descuento porcentual o monto fijo a la venta | P0 | 3 | Backlog |
| US-RT002-005 | Como cajero, quiero registrar pago en efectivo con cálculo de cambio | P0 | 3 | Backlog |
| US-RT002-006 | Como cajero, quiero registrar pago con tarjeta (terminal integrada) | P0 | 8 | Backlog |
| US-RT002-007 | Como cajero, quiero registrar pagos mixtos (parte efectivo, parte tarjeta) | P0 | 5 | Backlog |
| US-RT002-008 | Como cajero, quiero imprimir ticket de venta automáticamente | P0 | 3 | Backlog |
| US-RT002-009 | Como cajero, quiero que el POS funcione sin internet para no perder ventas | P0 | 8 | Backlog |
| US-RT002-010 | Como supervisor, quiero autorizar descuentos mayores al límite del cajero | P1 | 3 | Backlog |
| US-RT002-011 | Como cajero, quiero consultar puntos de cliente y aplicar canje | P1 | 5 | Backlog |
| US-RT002-012 | Como cajero, quiero cancelar venta parcial o totalmente | P1 | 3 | Backlog |
| US-RT002-013 | Como admin, quiero configurar impresoras y terminales de pago | P0 | 3 | Backlog |

**Total Story Points:** 55 SP

---

## Flujo de Venta

```
┌─────────────┐
│   INICIO    │  ← Cajero listo
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   ESCANER   │  ← Agregar productos
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   CARRITO   │  ← Revisar y aplicar descuentos
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    PAGO     │  ← Efectivo/Tarjeta/Mixto
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   TICKET    │  ← Imprimir comprobante
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  COMPLETADO │  ← Venta registrada
└─────────────┘
```

---

## Modos de Operación

```
┌─────────────────────────────────────────────────────────┐
│                   MODOS DEL POS                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ONLINE                                                 │
│  ├── Sincronización en tiempo real                      │
│  ├── Validación de stock central                        │
│  ├── Procesamiento de pagos con tarjeta                 │
│  └── Consulta de puntos de lealtad                      │
│                                                         │
│  OFFLINE (PWA)                                          │
│  ├── Catálogo de productos en cache                     │
│  ├── Ventas en cola para sincronizar                    │
│  ├── Solo pagos en efectivo                             │
│  ├── Cálculo local de puntos                            │
│  └── Sincronización automática al reconectar            │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Escaneo de código de barras (cámara o lector USB)
- [ ] Búsqueda de productos por nombre/SKU
- [ ] Carrito con totales en tiempo real
- [ ] Descuentos (porcentuales y fijos)
- [ ] Pagos: efectivo, tarjeta, mixtos
- [ ] Impresión de tickets
- [ ] Modo offline con sincronización
- [ ] Consulta y canje de puntos

**No Funcionales:**
- [ ] Agregar producto < 500ms
- [ ] Cierre de venta < 3 segundos
- [ ] PWA instalable en tablet/PC
- [ ] Funcionamiento offline 24+ horas

**Tecnicos:**
- [ ] Service Workers para offline
- [ ] IndexedDB para almacenamiento local
- [ ] Integración con impresoras ESC/POS
- [ ] Integración con terminales de pago

---

## Dependencias

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

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-RT-007 Caja | Requiere ventas para arqueo |
| EPIC-RT-008 Reportes | Requiere datos de ventas |
| EPIC-RT-010 Facturacion | Requiere ventas completadas |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `pos`
- [ ] Tablas: 7 (sales, sale_items, payments, terminals, printers, offline_queue, sessions)
- [ ] Funciones: 3 (calculate_totals, apply_discount, sync_offline)
- [ ] Indices: Por fecha, cajero, terminal, ticket

**Backend:**
- [ ] Modulo: `pos`
- [ ] Entities: 6 (Sale, SaleItem, Payment, Terminal, Printer, OfflineSale)
- [ ] Endpoints: 15
- [ ] Tests: 35

**Frontend (PWA):**
- [ ] Paginas: 4 (POSMain, ProductSearch, Payment, Config)
- [ ] Componentes: 20 (Cart, ProductCard, PaymentModal, Scanner, etc.)
- [ ] Stores: 2 (posStore, offlineStore)
- [ ] Service Workers: Offline + Sync

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/pos/sales | Crear venta |
| GET | /api/pos/sales/:id | Detalle de venta |
| POST | /api/pos/sales/:id/items | Agregar item |
| DELETE | /api/pos/sales/:id/items/:itemId | Quitar item |
| POST | /api/pos/sales/:id/discount | Aplicar descuento |
| POST | /api/pos/sales/:id/pay | Registrar pago |
| POST | /api/pos/sales/:id/complete | Cerrar venta |
| POST | /api/pos/sales/:id/cancel | Cancelar venta |
| POST | /api/pos/sync | Sincronizar ventas offline |
| GET | /api/pos/products/search | Buscar productos |
| GET | /api/pos/products/:barcode | Buscar por código |

---

## Integraciones de Hardware

| Dispositivo | Protocolo | Notas |
|-------------|-----------|-------|
| Lector código barras | USB HID / WebSerial | Actúa como teclado |
| Impresora tickets | ESC/POS | USB o red |
| Terminal bancaria | API propietaria | Depende del proveedor |
| Cajón de dinero | Pulso via impresora | RJ-11 conectado a impresora |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Fallas de sincronización | Media | Alto | Cola de reintentos + alertas |
| Hardware incompatible | Media | Medio | Lista de dispositivos probados |
| Pérdida de datos offline | Baja | Alto | Respaldo en múltiples stores |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Diseño de UI aprobado
- [ ] Hardware de prueba disponible

## Definition of Done (DoD)

- [ ] Flujo de venta completo funcionando
- [ ] Modo offline operativo
- [ ] Integración con impresora/lector
- [ ] Tests de integración pasando
- [ ] PWA instalable y funcional
- [ ] 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