# DIRECTIVA-PUNTO-VENTA

**Version:** 1.0
**Fecha:** 2025-12-08
**Vertical:** Retail / POS
**Nivel:** 2B.2

---

## PROPOSITO

Define las directrices para la implementacion del sistema de punto de venta (POS).

---

## ALCANCE

- Terminal de venta
- Sesiones de caja
- Procesamiento de pagos
- Cortes y arqueos
- Operacion offline

---

## PRINCIPIOS

### 1. Rendimiento Critico

El POS debe responder en menos de 100ms por transaccion:
- Busqueda de productos: < 50ms
- Calculo de totales: < 10ms
- Registro de venta: < 100ms

### 2. Disponibilidad

- El sistema debe funcionar offline
- Sincronizacion automatica cuando hay conexion
- No perder transacciones nunca

### 3. Seguridad en Efectivo

- Control estricto de sesiones de caja
- Movimientos de efectivo auditados
- Cortes obligatorios al cerrar

---

## FLUJO DE OPERACION

### Apertura de Caja

```
1. Cajero inicia sesion
   |
2. Verifica caja asignada
   |
3. Registra fondo inicial
   |
4. Sesion activa
```

### Venta

```
1. Escaneo/busqueda de producto
   |
2. Agregar al carrito
   |
3. Aplicar descuentos/promociones
   |
4. Calcular total
   |
5. Seleccionar metodo de pago
   |
6. Procesar pago
   |
7. Imprimir ticket
   |
8. Actualizar inventario
```

### Cierre de Caja

```
1. Iniciar corte
   |
2. Declarar efectivo fisico
   |
3. Sistema calcula esperado
   |
4. Registrar diferencias
   |
5. Cerrar sesion
```

---

## MODELO DE DATOS

### pos_sessions
```yaml
campos:
  - id: uuid
  - user_id: FK -> auth.users (cajero)
  - cash_register_id: FK -> cash_registers
  - opening_balance: decimal
  - closing_balance: decimal
  - expected_balance: decimal
  - difference: decimal
  - status: enum(open, closing, closed)
  - opened_at: timestamp
  - closed_at: timestamp
```

### pos_orders
```yaml
campos:
  - id: uuid
  - session_id: FK -> pos_sessions
  - customer_id: FK -> retail.customers (opcional)
  - order_number: string
  - subtotal: decimal
  - discount: decimal
  - tax: decimal
  - total: decimal
  - status: enum(draft, paid, refunded, cancelled)
  - payment_method: enum(cash, card, mixed)
  - created_at: timestamp
```

### cash_movements
```yaml
campos:
  - id: uuid
  - session_id: FK -> pos_sessions
  - movement_type: enum(sale, refund, cash_in, cash_out)
  - amount: decimal
  - payment_method: enum(cash, card)
  - reference: string
  - notes: text
  - created_at: timestamp
```

---

## OPERACION OFFLINE

### Datos en Cache Local

- Catalogo de productos
- Precios vigentes
- Promociones activas
- Clientes frecuentes

### Sincronizacion

```
[Terminal POS] <---> [Cola Local] <---> [Servidor Central]
       |                  |                    |
    Operacion         Buffer              Sincronizador
       |                  |                    |
    Cache            IndexedDB            PostgreSQL
```

### Conflictos

- El servidor tiene la version autoritativa
- Las ventas offline siempre se registran
- Los ajustes de inventario se reconcilian

---

## INTEGRACION CON HARDWARE

### Dispositivos Soportados

| Dispositivo | Protocolo | Notas |
|-------------|-----------|-------|
| Impresora tickets | ESC/POS | USB o Red |
| Lector codigo barras | HID | USB |
| Cajon de dinero | Pulso via impresora | - |
| Terminal bancaria | ISO 8583 | Integracion PAC |

### Arquitectura

```
[App POS]
    |
[Driver Layer]
    |
  +---+---+---+
  |   |   |   |
Print  Scan Drawer Card
```

---

## FACTURACION CFDI

### Flujo de Facturacion

1. Cliente solicita factura
2. Sistema recupera datos de venta
3. Genera XML CFDI 4.0
4. Envia a PAC para timbrado
5. Almacena UUID
6. Envia por email

### Consideraciones

- Facturacion global para tickets sin factura
- Complementos de pago para credito
- Cancelaciones dentro de plazo legal

---

## INTEGRACION CON ERP CORE

### Herencia de Specs

| Spec Core | Aplicacion |
|-----------|------------|
| SPEC-PRICING-RULES | Precios y promociones |
| SPEC-INVENTARIOS-CICLICOS | Conteos de tienda |
| SPEC-TRAZABILIDAD-LOTES-SERIES | Productos con caducidad |

### APIs a Extender

- `ProductService` -> `RetailProductService`
- `InventoryService` -> Multi-sucursal
- `InvoiceService` -> CFDI automatico

---

## METRICAS

| Metrica | Objetivo | Alerta |
|---------|----------|--------|
| Tiempo de venta | < 30 seg | > 60 seg |
| Disponibilidad | 99.9% | < 99% |
| Diferencias de caja | 0 | > $100 |
| Ventas sin factura | < 10% | > 20% |

---

## REFERENCIAS

- HERENCIA-SPECS-ERP-CORE.md
- DATABASE_INVENTORY.yml
- MASTER_INVENTORY.yml
- CFDI 4.0 SAT

---

**Documento de directiva oficial**