ElVendedorDocs

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.

Para implementadores4 min de lecturaActualizado el 16 de noviembre de 2026

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.

Diagrama de la red del restaurante: un router conecta la app de escritorio, que actúa como hub, con varios dispositivos móviles que envían comandas por WebSocket en la misma red local.
El escritorio es el hub de la red local; los móviles de la misma subred se conectan por WebSocket.

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, createdAt y, cuando aplica, expectedVersion.
  • El hub controla checkout_locked para 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

↑↓ para navegar · Enter para abrir · Esc para cerrar