# 🍕 Manual de Operaciones y Guía de Usuario: Vertical de Restaurantes, Pizzerías y Bares

**Sistema**: FacturaIridIA — Vertical Gastronómico y Punto de Venta Inteligente  
**Documento**: `docs/manual-usuario-restaurantes.md`  
**Dirigido a**: Dueños de Restaurantes, Encargados de Sala, Mesoneros (`WAITER`), Personal de Cocina y Barra (`KITCHEN`), Cajeros y Motorizados  
**Versión**: 1.0.0-PROD (Cumplimiento SNAT/2026/00093)  

---

## 1. Visión General del Circuito Gastronómico

El vertical de restaurantes y pizzerías de **FacturaIridIA** sustituye por completo el tradicional block de papel de notas por un circuito digital coordinado en tiempo real entre cuatro actores clave:

```text
┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   📱 MESONERO   │ ────> │   ⚡ BACKEND     │ ────> │ 🖥️ KDS / COCINA │ ────> │   💵 CAJA POS   │
│  Toma en mesa   │       │  Enrutamiento   │       │ Horno / Barra   │       │  Pre-Cuenta y   │
│  y comanda      │ <──── │  Alertas Push   │ <──── │  "¡Listo!" 🔔   │       │  Cobro Dividido │
└─────────────────┘       └─────────────────┘       └─────────────────┘       └─────────────────┘
```

1. **Mesonero en Mesa**: Abre la mesa desde su celular o tablet, selecciona platos, asigna modificadores (*"sin cebolla"*, *"mitad y mitad"*) y marcha la orden.
2. **Cocina y Barra (KDS)**: Recibe de inmediato la orden clasificada por área de preparación (`PIZZA_OVEN`, `BAR`, `KITCHEN`), avanza los estados y notifica cuando el plato está listo.
3. **Aviso de Retiro**: Al marcar "Listo", el celular del mesonero suena y vibra indicando que el plato está caliente para llevar.
4. **Caja Principal**: Mantiene el saldo de la mesa actualizado en dólares ($) y bolívares (Bs. BCV), emite la pre-cuenta y divide la cuenta (*Split Bill*) con cuadre matemático exacto al céntimo.

---

## 2. Guía del Mesonero: Comanda Virtual Móvil (Rol `WAITER`)

### 2.1 Acceso Rápido y Selección de Mesa
1. Abra la PWA de FacturaIridIA en su teléfono o tablet (`/#/pos`).
2. Si su usuario tiene asignado el rol **Mesonero (`WAITER`)**, la app abrirá directamente el **Plano de Salón y Barra**.
3. Seleccione el área correspondiente:
   - 🍽️ **Salón** (`Mesa 1..12`)
   - 🌿 **Terraza** (`T-01..T-06`)
   - 🍺 **Barra** (`Barra 1..6`)
4. Toque una mesa verde (**Libre**) para iniciar la sesión. Indique el número de comensales y, si lo desea, un alias identificador (ej. *"Cumpleaños Ana"* o *"Camisa Azul"*).

```text
+-------------------------------------------------------------------------------+
| 🍽️ SALÓN (12)    🌿 TERRAZA (6)    🍺 BARRA (6)   [⚙️ Mesas: [-] 12 [+] ]     |
+-------------------------------------------------------------------------------+
|  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  |
|  │ 🟢 MESA 1    │   │ 🟡 MESA 2    │   │ 🔵 MESA 3    │   │ 🟣 MESA 4      │  |
|  │ Libre (4p)   │   │ Carlos · 15m │   │ Pre-Cuenta   │   │ Pagado 1/2     │  |
|  │              │   │ 🔔 1 ¡LISTA! │   │ $42.00 USD   │   │ Resta $14.00   │  |
|  └──────────────┘   └──────────────┘   └──────────────┘   └────────────────┘  |
+-------------------------------------------------------------------------------+
```

---

### 2.2 Selección de Productos, Modificadores y Pizzería Mitad y Mitad
1. Toque cualquier plato o bebida para abrir el panel táctil de especificaciones.
2. **Modificadores con y sin costo**:
   - Toque preferencias rápidas: *"Sin cebolla"*, *"Salsa tártara aparte"*, *"Término medio"*.
   - Agregue extras con recargo automático en `$ USD` (ej. *"Extra Queso Parmesano +$1.50"*).
3. **Pizzería Especial — Mitad y Mitad (`HALF_AND_HALF`)**:
   - Seleccione el tamaño de la pizza (ej. *Familiar 8 Porciones*).
   - Active la casilla **"Mitad y Mitad"**:
     - **Mitad Izquierda**: Seleccione *Pepperoni Especial*.
     - **Mitad Derecha**: Seleccione *Cuatro Quesos*.
   - **Regla de Precio**: El sistema aplica automáticamente la regla `MAX_HALF` (cobra la mitad de mayor valor) para proteger el margen de ganancia del local.
   - Elija borde especial si aplica (*"Borde relleno de queso"*) y agregue notas para el pizzero.

```text
+-------------------------------------------------------------+
| 🍕 MODIFICADORES DE PIZZA: Familiar 8 Porciones             |
+-------------------------------------------------------------+
| [x] Dividir Mitad y Mitad (Regla: Cobra mitad de mayor precio)
|                                                             |
| Mitad 1 (Izquierda): [ Pepperoni Especial ($14.00)  ▼ ]     |
| Mitad 2 (Derecha):   [ Cuatro Quesos      ($16.00)  ▼ ]     |
|                                                             |
| Borde Especial:      ( ) Normal  (o) Borde de Queso (+$2.00)|
| Preferencias:        [x] Sin aceitunas negras               |
|                      [x] Orégano aparte                     |
|                                                             |
| Tiempo de Cocina:    (o) 1° Tiempo (Entrada)                |
|                      ( ) 2° Tiempo (Plato Fuerte)           |
|                                                             |
| Asignar a Silla:     [ Silla 1 ] [ Silla 2 ] [ Mesa Centro ]|
|                                                             |
|                   [ AGREGAR A LA COMANDA ]                  |
+-------------------------------------------------------------+
```

---

### 2.3 Tiempos de Cocina (*Hold & Fire*) y Envío de Rondas
1. Si los comensales piden entradas y platos fuertes en el mismo momento, marque los platos fuertes como **2° Tiempo (Plato Fuerte)**.
2. Al culminar la toma, pulse **`[🔥 Marchar Ronda #1]`**.
3. El sistema realiza la **Impresión Delta**: solo envía a cocina los platos nuevos recién agregados, agrupándolos automáticamente por su estación de preparación:
   - Las pizzas van directo a la pantalla/impresora del **Horno de Pizza**.
   - Los tequeños y pastas van a **Cocina Principal**.
   - Los mojitos y cervezas van a la **Barra de Tragos**.
4. Cuando los clientes terminen la entrada, abra la mesa y pulse **`[Marchar 2° Tiempo]`** para que cocina inicie la preparación de los platos fuertes calientes.

---

### 2.4 Recepción de la Alerta: "¡Mesa X Lista en Cocina!"
- Cuando el cocinero o pizzero marca la orden como **`READY`**, la PWA emite en el celular del mesonero una **notificación visual flotante con vibración y sonido**:
  > **`🔔 ¡Mesa 4 Lista en Horno! (1x Pizza Familiar 1/2 Pepperoni 1/2 4 Quesos)`**
- El mesonero pasa al pasaplatos, retira la bandeja y al entregar en la mesa pulsa **`[✅ Marcar Servido]`**.

---

## 3. Guía de Cocina, Horno y Barra: Pantalla KDS (Rol `KITCHEN`)

La pantalla KDS (*Kitchen Display System*) sustituye las comandas de papel en los fogones y barras. Se encuentra en la ruta `/pos/cocina` o seleccionando la vista de cocina en el menú lateral.

```text
+-------------------------------------------------------------------------------+
| 👨‍🍳 KDS COCINA & BARRA | Estación: [ Todas ] [ Horno ] [ Cocina ] [ Barra ]    |
+-------------------------------------------------------------------------------+
| ┌───────────────────────────┐  ┌───────────────────────────┐  ┌─────────────┐ |
| │ 🟡 ORDEN #14 · MESA 4     │  │ 🟠 ORDEN #15 · BARRA 2    │  │ 🟢 ORDEN #12│ |
| │ Mesonero: Carlos · Hace 4m│  │ Mesonero: Ana · Hace 8m   │  │ Hace 14m    │ |
| │ Ronda #1 (Horno Pizzas)   │  │ Ronda #1 (Barra Bebidas)  │  │ ¡LISTA! 🔔  │ |
| ├───────────────────────────┤  ├───────────────────────────┤  ├─────────────┤ |
| │ • 1x Pizza Familiar       │  │ • 2x Mojito Clásico       │  │ • 1x Pasta  │ |
| │   1/2 Pepperoni / 1/2 4Q  │  │   (Poco hielo)            │  │   Boloña    │ |
| │   NOTA: Borde de Queso    │  │ • 1x Polar Pilsen Fría    │  │             │ |
| ├───────────────────────────┤  ├───────────────────────────┤  ├─────────────┤ |
| │ [👨‍🍳 EN PREPARACIÓN]     │  │ [👨‍🍳 EN PREPARACIÓN]     │  │ [✅ SERVIDO]│ |
| │ [🔔 ¡PLATO LISTO!]        │  │ [🔔 ¡BEBIDA LISTA!]       │  │             │ |
| └───────────────────────────┘  └───────────────────────────┘  └─────────────┘ |
+-------------------------------------------------------------------------------+
```

### 3.1 Filtro por Estación de Trabajo
En la parte superior de la pantalla, cada cocinero puede seleccionar su área:
- **`PIZZA_OVEN`**: Muestra únicamente las pizzas, calzones y panes de ajo.
- **`KITCHEN`**: Muestra hamburguesas, carnes, ensaladas y guarniciones.
- **`BAR`**: Muestra cervezas, cócteles, jugos y bebidas.
- **`DESSERTS`**: Muestra dulces, cafés y postres.

### 3.2 Semáforo de Tiempos y Estados
- 🟡 **`PENDING` (Recibido)**: Comanda recién enviada por el mesonero.
- 🟠 **`PREPARING` (En Preparación)**: El cocinero tocó la orden al meterla al fuego/horno.
- 🟢 **`READY` (Listo para Retirar)**: La comida está emplatada en el pasaplatos. Dispara la alerta al celular del mesonero.
- ⚪ **`SERVED` (Entregado)**: La comanda desaparece de la pantalla activa de cocina y queda registrada en el historial.

### 3.3 Control de Mermas y Cancelaciones Anti-Fraude
Si un cliente pide anular un plato que ya fue marchado a cocina:
1. El sistema no permite el borrado simple. Exige **PIN de Autorización del Encargado/Administrador**.
2. Al ingresar el PIN, el sistema pregunta: **«¿El plato ya se preparó?»**
   - **Sí (Merma / Desperdicio)**: Se descuentan los insumos del inventario bajo la cuenta contable de merma y se imprime un ticket rojo en cocina: **`🚫 ANULADO: 1x Pizza Familiar`**.
   - **No (No se preparó)**: Se detiene la preparación en KDS y no se afecta el inventario.

---

## 4. Guía de Caja y Facturación: Cierre, Pre-Cuenta y Split Bill

### 4.1 Solicitud e Impresión de la Pre-Cuenta (No Fiscal)
Cuando los clientes piden la cuenta:
1. El mesonero o cajero abre la mesa y pulsa **`[📄 Solicitar Pre-Cuenta]`**.
2. La mesa cambia a estado azul **`BILL_REQUESTED`**.
3. Se imprime el ticket térmico con la leyenda obligatoria:
   > **`ESTADO DE CUENTA — DOCUMENTO NO FISCAL`**
4. La pre-cuenta desglosa los consumos, el **10% de Servicio Sugerido** (si aplica para la modalidad `DINE_IN`) y el total equivalente en **Bolívares (VES)** calculado con la **Tasa oficial del BCV del día**.

---

### 4.2 Las 3 Modalidades de División de Cuenta (*Split Bill*)
Al pulsar **`[💳 Dividir Cuenta en Caja]`**, se despliega el modal interactivo con tres opciones:

```text
+-------------------------------------------------------------------------------+
| 🪓 DIVISIÓN DE CUENTA: MESA 4 ($39.60 USD / Bs. 1.633,67)                     |
+-------------------------------------------------------------------------------+
| Modalidad:  (o) Partes Iguales      ( ) Por Comensal (Sillas)   ( ) Compartido|
|                                                                               |
| Cantidad de personas: [ - ] 3 [ + ]                                           |
|                                                                               |
| • Sub-Cuenta #1 (Parte 1/3): $13.20 USD  (Bs. 544,56)  [ COBRAR ESTA PARTE ]  |
| • Sub-Cuenta #2 (Parte 2/3): $13.20 USD  (Bs. 544,56)  [ COBRAR ESTA PARTE ]  |
| • Sub-Cuenta #3 (Parte 3/3): $13.20 USD  (Bs. 544,55)  [ COBRAR ESTA PARTE ]  |
|                                                                               |
| [!] Cuadre perfecto: La suma de partes cuadra al céntimo exacto sin pérdidas  |
+-------------------------------------------------------------------------------+
```

1. **Modalidad 1 — En Partes Iguales**:
   - Indique la cantidad de comensales (ej. 3 personas).
   - El motor matemático (`bill-splitter.util.ts`) utiliza el algoritmo de **Mayor Residuo (*Largest Remainder*)**: reparte los céntimos indivisibles equitativamente para que la suma en VES y USD sea idéntica al total de la mesa al 100%.
2. **Modalidad 2 — Por Comensal (Asientos / Sillas)**:
   - Cada persona paga exclusivamente lo que consumió en su asiento (`Silla 1`, `Silla 2`, etc.).
3. **Modalidad 3 — Platos Compartidos**:
   - Platos de picar (ej. una jarra de sangría o una bandeja de tequeños de $12.00) pueden dividirse en $1/2$, $1/3$ o $1/4$ entre las sub-cuentas seleccionadas.

---

### 4.3 Cierres Parciales de Mesa (`PARTIALLY_PAID`)
Si uno de los comensales debe marcharse temprano:
1. El cajero selecciona solo la sub-cuenta de ese comensal y pulsa **`[Cobrar Sub-Cuenta]`**.
2. Se procesa el pago (ej. Pago Móvil o Divisa en efectivo) y se emite su Factura o Recibo.
3. La mesa pasa automáticamente al estado morado **`PARTIALLY_PAID`**.
4. La mesa permanece abierta para los demás clientes, quienes pueden seguir pidiendo rondas adicionales.
5. **Liberación Automática**: Solo cuando la última sub-cuenta pendiente es cobrada, la mesa se libera y vuelve a color verde **`FREE`**.

---

## 5. Módulo de Delivery y Despacho Gastronómico

Para pedidos a domicilio y por WhatsApp:

```text
+-------------------------------------------------------------------------------+
| 🛵 DESPACHO DE DELIVERY: Pedido #DEL-042                                      |
+-------------------------------------------------------------------------------+
| Cliente: Juan Pérez                 Teléfono: 0412-1234567                    |
| Dirección: Urb. Los Samanes, Calle 3, Quinta Bella Vista (Pto Ref: Frente panadería)
|                                                                               |
| Zona de Envío: [ Zona 2 - Este ($2.50 USD)                     ▼ ]            |
| Condición de Pago:                                                            |
| ( ) PREPAID_VERIFIED (Pago Móvil confirmado en banco antes de preparar)       |
| (o) CASH_ON_DELIVERY (Efectivo en divisas al entregar)                        |
|                                                                               |
| Total del Pedido: $18.00  +  Envío: $2.50  =  Total a Cancelar: $20.50 USD    |
| Cliente pagará con billete de: [ $50.00 USD ]                                 |
| Vuelto que debe llevar el Motorizado: [ $29.50 USD ] (Bs. 1.216,99)           |
|                                                                               |
| Asignar a Motorizado: [ José Moto (Bera SBR Azul)             ▼ ]             |
|                                                                               |
|      [ DESPACHAR PEDIDO ]                  [ IMPRIMIR HOJA DE RUTA ]          |
+-------------------------------------------------------------------------------+
```

### 5.1 Búsqueda Rápida por Teléfono
- Ingrese el número del cliente; el sistema recupera al instante su nombre, direcciones previas y puntos de referencia.

### 5.2 Semáforo de Cobro de Delivery
- **`PREPAID_VERIFIED`**: Úselo para pedidos pagados previamente por **Pago Móvil** o transferencia. Cocina no inicia la preparación hasta que la referencia bancaria esté validada.
- **`CASH_ON_DELIVERY` (Efectivo contra entrega)**: Indique la denominación del billete con que pagará el cliente (ej. billete de `$50`). El sistema calcula automáticamente el vuelto en divisas y bolívares:
  > **`El motorizado debe llevar $29.50 de vuelto exacto.`**
- La hoja de ruta impresa para el repartidor muestra el vuelto a entregar, los números de contacto y el enlace con ubicación GPS.

### 5.3 Liquidación y Arqueo de Motorizados al Cierre
Al finalizar el turno o regresar de ruta:
1. Ingrese a la liquidación de despachos en caja.
2. El sistema muestra la lista de viajes realizados por cada chofer, el efectivo entregado para cambio, el efectivo cobrado y la comisión de entrega correspondiente.
3. El cajero recibe el neto de las cuentas y libera la hoja de ruta del repartidor.
