Red del restaurante (hub LAN)
Cómo montar el hub del escritorio, conectar tablets y teléfonos en la misma red y diagnosticar por qué no llegan las comandas.
En modo restaurante, el escritorio es el hub de la red local y los móviles son clientes que consultan mesas, envían comandos y escuchan eventos. La operación diaria no depende de internet: la nube queda para el respaldo y el sync posterior. Aquí verás cómo dejarlo operativo y cómo aislar el fallo.
Arquitectura hub-and-spoke
| Papel | Quién | Qué hace |
|---|---|---|
| Hub | el-vendedor-desktop |
Autoridad operacional: guarda mesas, órdenes y estados; expone HTTP y WebSocket. |
| Spoke | App móvil (mesero, cajero, cocina) | Consulta mesas y órdenes, envía comandos y escucha eventos. |
| Nube | el-vendedor-back |
Recibe después la venta cerrada; no participa del flujo vivo. |
Reglas que no debes romper al dar soporte:
- Las comandas abiertas no son ventas contables; la venta se genera al cobrar.
- El inventario se descuenta al confirmar el pago, no al agregar productos.
- Los comandos son idempotentes y llevan
commandId,deviceId,userId,role,createdAty, cuando aplica,expectedVersion. - El hub controla
checkout_lockedpara evitar el doble cobro.
Descubrimiento y conexión
No hay descubrimiento automático documentado: el móvil se configura a mano. La pantalla de restaurante LAN de la app pide IP, puerto, token, nombre de dispositivo y POS asignado, y guarda todo en restaurant_lan_hub_config_v1.
El escritorio arranca el servidor al iniciar Electron, escucha en 0.0.0.0 y usa el puerto 3897 por defecto. Si ese puerto está ocupado, toma uno libre: comprueba el puerto real en la vista Restaurante LAN, que además muestra la IP y el token que hay que llevar al móvil.
Endpoints del hub:
| Método | Ruta | Uso |
|---|---|---|
GET |
/api/restaurant/hub/health |
Prueba de vida. |
GET |
/api/restaurant/hub/info |
Datos del hub y su puerto. |
GET |
/api/restaurant/tables |
Tablero de mesas. |
GET |
/api/restaurant/orders/open |
Órdenes abiertas. |
POST |
/api/restaurant/commands |
Envío de comandos. |
WS |
/ws/restaurant?token=...&deviceId=... |
Eventos en tiempo real. |
Cabeceras esperadas en cada llamada:
Authorization: Bearer <token>
X-Restaurant-Device-Id: <deviceId>Hay dos clases de token: el token del equipo autoriza cualquier restaurante del hub y vive en restaurant-lan-hub-token.txt; el token de restaurante (uno por posId) solo autoriza el suyo y es el que se reparte por QR a las tablets. Ambos están en el directorio de datos de la aplicación, junto a restaurant-lan-hub-state.json.
Flujo de comanda y cobro
Estados de mesa: available, occupied, checkout_requested, checkout_locked, disabled. Estados de orden: open, sent_to_kitchen, checkout_requested, checkout_locked, paid, cancelled. Estados de línea: draft, sent, preparing, ready, served, cancelled.
Comandos disponibles: open_table, add_order_item, update_order_item, void_order_item, send_to_kitchen, mark_item_preparing, mark_item_ready, mark_item_served, request_checkout, lock_checkout, confirm_payment, close_table.
Reparto por rol: el mesero abre mesas, agrega y envía a cocina, y solicita la cuenta; el cajero o el dueño bloquean la cuenta, confirman el pago y liberan la mesa. Los botones de cobro solo aparecen si el rol tiene canChargeRestaurantOrders.
Eventos que emite el hub: hub_status, table_updated, order_created, order_updated, order_line_updated, checkout_requested, checkout_locked, payment_confirmed.
Requisitos de red
| Requisito | Detalle |
|---|---|
| Misma subred | Escritorio y móviles en el mismo WiFi o switch. |
| IP del hub | Fija o reservada por DHCP. Si cambia, las tablets dejan de conectar. |
| Firewall del equipo | Permitir conexiones entrantes a ese puerto. |
| Aislamiento de clientes | Si el punto de acceso aísla clientes entre sí, los móviles no verán al hub: desactívalo. |
| Cobertura | Sin cortes ni roaming agresivo: si el WebSocket cae, hay que reconectar. |
Límites de dispositivos
Los móviles que se conectan al hub no consumen ranuras de licencia; las ranuras (LICENSING_DEFAULT_ACTIVATIONS_LIMIT, 3 por defecto) cuentan equipos activados para sincronizar. Cada tablet se apunta a un POS y recibe el token de ese restaurante.
Pendiente de validación
- El hub no impone un máximo de conexiones: no hay límite documentado de dispositivos simultáneos. Antes de prometer «hasta N tablets», pruébalo con el hardware del cliente.
- Tampoco hay requisitos documentados de punto de acceso (modelo, banda, cobertura mínima). Valídalos con quien diseñe la red del local.
- El recorrido completo pedido → cocina → cobro → cierre de mesa está pendiente de verificación manual con hardware real.
Diagnóstico
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| El móvil no conecta | IP o puerto equivocados, subred distinta, firewall cerrado. | Comprueba el puerto real en la vista del hub y prueba GET /api/restaurant/hub/health desde el móvil. |
| Conecta y se desconecta | WiFi inestable, suspensión del equipo, token renovado. | Revisa el estado de red y vuelve a leer el token en el escritorio. |
| Las comandas no llegan | POS o posId distintos, token de otro restaurante, rol sin permiso. |
Compara el POS asignado en la tablet con el del hub y revisa los permisos del rol. |
| Cobra dos veces la misma mesa | No se respetó checkout_locked. |
Bloquea la cuenta antes de cobrar y revisa expectedVersion en el comando. |
Qué no atraviesa el backend
Mesas, órdenes abiertas, líneas y eventos del hub no viajan por el sync: viven en el hub. Al confirmar el pago se sincroniza la venta cerrada. Los planos de salón (restaurant_layouts) solo los empuja el escritorio, y no existe pipeline de eventos de inventario: el stock viaja como snapshot de producto y eventos discretos.
Siguiente paso
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte