erp-retail-backend-v2/docs/SPRINT-6-SUMMARY.md

# Sprint 6: POS Backend - Resumen

## Objetivo
Completar y mejorar el módulo de Punto de Venta (POS) con funcionalidades avanzadas: reembolsos, órdenes en espera (hold/recall), integración con cupones y estadísticas de sesión.

## Estado Inicial
El módulo POS ya contaba con funcionalidades base:
- Apertura/cierre de sesiones
- Creación de órdenes y líneas
- Procesamiento de pagos múltiples
- Anulación de órdenes
- Búsqueda de órdenes

## Componentes Mejorados

### 1. POSOrderService (Mejoras)

#### Nuevos Métodos de Reembolso:
- **createRefund()**: Crea orden de reembolso desde orden original
  - Valida orden original pagada
  - Valida cantidades a reembolsar
  - Genera líneas negativas
  - Relaciona con orden original

- **processRefundPayment()**: Procesa pago de reembolso
  - Genera movimiento de efectivo negativo
  - Actualiza totales de sesión
  - Marca reembolso como completado

#### Nuevos Métodos Hold/Recall:
- **holdOrder()**: Pone orden en espera ("parking")
  - Solo aplica a órdenes en draft
  - Guarda nombre/referencia de la orden
  - Cambia estado a confirmado con metadata

- **getHeldOrders()**: Lista órdenes en espera por sucursal

- **recallOrder()**: Recupera orden en espera
  - Asigna a sesión/caja actual
  - Vuelve a estado draft

#### Métodos Adicionales:
- **applyCouponToOrder()**: Aplica cupón a orden
- **markReceiptPrinted()**: Marca ticket como impreso
- **sendReceiptEmail()**: Envía ticket por correo
- **getSessionStats()**: Estadísticas de sesión

### 2. Controladores Nuevos

**Endpoints de Reembolso (2):**
| Método | Ruta | Descripción | Permisos |
|--------|------|-------------|----------|
| POST | `/pos/refunds` | Crear reembolso | supervisor+ |
| POST | `/pos/refunds/:id/process` | Procesar pago | supervisor+ |

**Endpoints Hold/Recall (3):**
| Método | Ruta | Descripción |
|--------|------|-------------|
| POST | `/pos/orders/:id/hold` | Poner en espera |
| GET | `/pos/orders/held` | Listar en espera |
| POST | `/pos/orders/:id/recall` | Recuperar orden |

**Endpoints Adicionales (4):**
| Método | Ruta | Descripción |
|--------|------|-------------|
| POST | `/pos/orders/:id/coupon` | Aplicar cupón |
| POST | `/pos/orders/:id/receipt/print` | Marcar impreso |
| POST | `/pos/orders/:id/receipt/send` | Enviar email |
| GET | `/pos/sessions/:id/stats` | Estadísticas |

**Total nuevos endpoints: 9**
**Total endpoints POS: 21**

### 3. Validación Zod (Nuevos Schemas)

```typescript
// Refunds
refundLineSchema
createRefundSchema
processRefundPaymentSchema

// Hold/Recall
holdOrderSchema
recallOrderSchema

// Coupon
applyCouponSchema
```

## Estructura de Archivos

```
src/modules/pos/
├── controllers/
│   └── pos.controller.ts    (605 líneas)
├── entities/
│   ├── index.ts
│   ├── pos-session.entity.ts
│   ├── pos-order.entity.ts
│   ├── pos-order-line.entity.ts
│   └── pos-payment.entity.ts
├── routes/
│   └── pos.routes.ts        (143 líneas)
├── services/
│   ├── index.ts
│   ├── pos-session.service.ts (361 líneas)
│   └── pos-order.service.ts   (915 líneas)
├── validation/
│   └── pos.schema.ts        (207 líneas)
└── index.ts
```

## Flujos de Negocio

### Flujo de Reembolso
```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Original   │────▶│   Create    │────▶│   Refund    │
│   Order     │     │   Refund    │     │   (draft)   │
│   (paid)    │     │             │     │             │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                                               ▼
                    ┌─────────────┐     ┌─────────────┐
                    │   Refund    │◀────│   Process   │
                    │   (paid)    │     │   Payment   │
                    └─────────────┘     └─────────────┘
```

### Flujo Hold/Recall
```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Order     │────▶│    Hold     │────▶│   Order     │
│   (draft)   │     │   Order     │     │   (held)    │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
      ┌────────────────────────────────────────┘
      │
      ▼
┌─────────────┐     ┌─────────────┐
│   Recall    │────▶│   Order     │
│   Order     │     │   (draft)   │
└─────────────┘     └─────────────┘
```

## Tipos de Orden

| Tipo | Código | Descripción |
|------|--------|-------------|
| SALE | sale | Venta normal |
| REFUND | refund | Devolución |
| EXCHANGE | exchange | Cambio |

## Estados de Orden

| Estado | Descripción |
|--------|-------------|
| DRAFT | Orden en proceso |
| CONFIRMED | Confirmada / En espera (hold) |
| PAID | Pagada completamente |
| PARTIALLY_PAID | Pago parcial |
| VOIDED | Anulada |
| REFUNDED | Reembolsada |

## Permisos Requeridos

| Acción | Roles Permitidos |
|--------|------------------|
| Crear orden | Todos autenticados |
| Agregar pago | Todos autenticados |
| Anular orden | admin, manager, supervisor |
| Crear reembolso | admin, manager, supervisor |
| Procesar reembolso | admin, manager, supervisor |
| Hold/Recall | Todos autenticados |

## Estadísticas de Sesión

El endpoint `/pos/sessions/:id/stats` devuelve:
```typescript
{
  totalOrders: number;      // Órdenes completadas
  totalSales: number;       // Ventas totales
  totalRefunds: number;     // Reembolsos totales
  totalDiscounts: number;   // Descuentos aplicados
  averageTicket: number;    // Ticket promedio
  paymentBreakdown: {       // Desglose por método
    cash: number;
    credit_card: number;
    debit_card: number;
    // ...
  };
}
```

## Integración Pendiente

- [ ] Integración completa con PriceEngineService para cupones
- [ ] Envío real de email para receipts
- [ ] Generación de PDF de ticket
- [ ] Integración con impresora térmica

## Dependencias

- TypeORM 0.3.x
- Zod para validación
- BaseService para operaciones CRUD
- Middleware de autenticación y roles

## Próximos Pasos

Sprint 7 según roadmap: POS Frontend
- Layout de interfaz POS
- Pantalla de ventas
- Pantalla de cobro
- Componentes de producto
- Componentes de pago