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)

// 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:

{
  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