# 03 · Flujo de la App — User Journey

**Proyecto:** Sistema Boutique (POS + Tienda Online)
**Versión:** 1.0

Hay **dos recorridos distintos** porque hay dos usuarios distintos: el **cajero** (velocidad) y el **cliente online** (exploración). Cada uno tiene sus pantallas.

---

> **Regla de stock disponible (aplica a ambos recorridos):**
> `stock_disponible = product_variants.stock − Σ stock_reservations.quantity WHERE expires_at > now()`
> El stock físico (`product_variants.stock`) **no se toca al reservar**; solo se descuenta definitivamente en la transacción atómica al confirmar la venta o el pago. Las reservas expiradas se ignoran automáticamente en el cálculo.

---

## PARTE A — Recorrido del Cajero (POS)

### Pantallas del POS

| # | Pantalla | Propósito |
|---|----------|-----------|
| P1 | Login | Autenticación del cajero/admin |
| P2 | Terminal de venta | Pantalla principal — donde ocurre el 90% del trabajo |
| P3 | Búsqueda de producto | Modal/panel para hallar producto sin código |
| P4 | Cobro | Selección de método de pago y cálculo de vuelto |
| P5 | Cliente | Alta rápida / selección de cliente |
| P6 | Inventario | Ingreso y ajuste de mercancía (según rol) |
| P7 | Reportes | Ventas, comisiones, stock (según rol) |

### Flujo de una venta (el camino crítico)

```
[Login P1]
   │  cajero entra con usuario y contraseña
   ▼
[Terminal de venta P2]  ← pantalla de inicio del cajero
   │
   │  El cursor está SIEMPRE listo para escanear.
   │
   ├─▶ Escanea código de barras
   │      → el lector "teclea" el código + Enter
   │      → el sistema busca la variante (talla+color) y la agrega al carrito
   │      → el stock disponible se muestra al instante
   │
   ├─▶ ¿No hay etiqueta? → abre [Búsqueda P3]
   │      → busca por nombre/referencia, elige variante, agrega al carrito
   │
   ├─▶ (opcional) Aplica descuento a una línea o al total
   │      → el sistema valida que no supere el límite del rol
   │
   ├─▶ (opcional) Asocia un cliente → [Cliente P5]
   │      → busca por celular o crea uno nuevo en 2 campos
   │      → activa beneficios de fidelización si aplica
   │
   ▼
[Botón "COBRAR"] → abre [Cobro P4]
   │
   │  Elige método: efectivo / tarjeta / transferencia / mixto
   │  Si es efectivo: ingresa monto recibido → el sistema calcula el vuelto
   │
   ▼
[Botón "CONFIRMAR VENTA"]
   │  → TRANSACCIÓN ATÓMICA:
   │     1. valida stock de cada variante
   │     2. descuenta stock (queda no disponible también para la tienda online)
   │     3. registra la venta atribuida al vendedor
   │     4. calcula la comisión del vendedor
   │     5. registra el movimiento de inventario (kardex)
   │  → si algo falla, TODO se revierte (no hay venta a medias)
   │
   ▼
[Recibo generado]  → PDF en pantalla (impresión térmica en Fase 9)
   │
   ▼
[Vuelve a Terminal P2, carrito limpio]  ← listo para el siguiente cliente
```

**Acciones de los botones principales del POS:**

| Botón | Acción exacta |
|-------|---------------|
| (escaneo) | Busca variante por `barcode`, la agrega al carrito, muestra stock |
| **Buscar** | Abre panel de búsqueda por nombre/referencia |
| **Descuento** | Abre input de descuento; valida contra el límite del rol |
| **Cliente** | Abre selector/alta de cliente |
| **Cobrar** | Abre pantalla de cobro con el total calculado |
| **Confirmar venta** | Ejecuta la transacción atómica de venta |
| **Cancelar** | Vacía el carrito sin tocar el stock |

---

## PARTE B — Recorrido del Cliente (Tienda Online)

### Pantallas de la Tienda

| # | Pantalla | Propósito |
|---|----------|-----------|
| T1 | Inicio / Catálogo | Vitrina con productos y filtros |
| T2 | Ficha de producto | Detalle, galería, selector de talla/color |
| T3 | Carrito | Resumen de lo que va a comprar |
| T4 | Login / Registro | Necesario para comprar |
| T5 | Checkout | Dirección + pago |
| T6 | Confirmación | Pedido realizado |
| T7 | Mi cuenta | Historial de pedidos, direcciones, fidelización |

### Flujo de compra

```
[Inicio / Catálogo T1]
   │  el visitante ve productos con foto, precio y "disponible"
   │  filtra por tipo, color, talla, precio
   │
   ▼
[Ficha de producto T2]
   │  ve galería, descripción, precio
   │  elige TALLA y COLOR (una variante)
   │  → el sistema muestra el stock real de esa variante
   │  → si esa combinación está agotada, el botón se deshabilita
   │
   ▼
[Botón "Agregar al carrito"]
   │  → agrega la variante elegida al carrito
   │
   ▼
[Carrito T3]
   │  ve las prendas, cantidades, subtotal, IVA, total en COP
   │  puede cambiar cantidades o quitar
   │
   ▼
[Botón "Ir a pagar"]
   │  → ¿no ha iniciado sesión? → [Login/Registro T4]
   │
   ▼
[Checkout T5]
   │  elige: envío a dirección  o  retiro en tienda
   │  → el carrito RESERVA el stock temporalmente (tabla stock_reservations)
   │  → la reserva expira en 15 minutos (configurable: checkout.reservation_ttl_minutes en settings)
   │  → si el cliente no completa el pago en ese tiempo, la reserva se libera automáticamente
   │
   ▼
[Botón "Pagar"] → redirige a Wompi
   │  el cliente paga en la pasarela colombiana
   │
   ├─▶ Pago aprobado
   │      → confirma el pedido
   │      → descuenta stock definitivamente (transacción atómica, igual que el POS)
   │      → registra el pedido en el historial
   │      → suma puntos de fidelización
   │      → [Confirmación T6] + correo
   │
   └─▶ Pago rechazado / abandonado
          → libera la reserva de stock
          → el carrito queda intacto para reintentar
```

**Acciones de los botones principales de la Tienda:**

| Botón | Acción exacta |
|-------|---------------|
| **Filtrar** | Aplica filtros al catálogo (tipo, color, talla, precio) |
| **Agregar al carrito** | Añade la variante seleccionada; deshabilitado si agotada |
| **Ir a pagar** | Verifica sesión; si no hay, envía a login/registro |
| **Pagar** | Crea reserva de stock (TTL 15 min, configurable) en `stock_reservations` y redirige a Wompi |
| **(webhook Wompi)** | Al confirmar pago, ejecuta la venta atómica y libera/consume la reserva |

---

## Punto de encuentro de ambos recorridos

Los dos flujos —cajero y cliente— terminan en la **misma transacción atómica de descuento de stock** sobre la **misma tabla de inventario**. Esa es la garantía de que jamás se venda dos veces la misma prenda. Es el corazón del sistema.