Saltar a contenido

Camarero IA — Visión general

Camarero IA es un sistema de pedidos por QR para bares y restaurantes con un camarero virtual basado en IA. El cliente escanea un código QR en su mesa, conversa con la IA en su propio idioma, y la conversación se traduce en una comanda (la orden de cocina) que pasa por validación automática de IA, aprobación del manager, preparación en cocina y, finalmente, servicio y pago.

Esta página explica qué es el sistema y cómo fluye un pedido de principio a fin. Si lo que quieres es ponerlo en marcha, salta a Empezar; si quieres entender las decisiones de diseño, ve a Arquitectura.

Pensado para personas y para LLMs

Esta documentación define los términos clave (sesión, comanda, estados) de forma explícita y sin ambigüedad, para que la lean igual de bien las personas y los agentes de IA que trabajan sobre el código.

Términos clave

Definiciones que se usan en toda la documentación:

Término Definición
TableSession Sesión de una mesa: se abre cuando el cliente escanea el QR y dura toda la visita (la ventana de jornada es larga, no un timeout de inactividad). Agrupa todas las comandas de esa mesa.
Comanda La orden de cocina. Es el término canónico que sustituye a "order" y "batch". Una sesión puede tener varias comandas (rondas) y cada comanda tiene líneas (ComandaLine).
Línea de comanda Cada ítem pedido dentro de una comanda: producto, cantidad, extras, comentario y precio (siempre en céntimos).
Validación IA Revisión automática de la comanda antes de pasar al manager. Es fail-closed: ante un fallo, se rechaza o se escala, nunca se auto-aprueba.
Aprobación del manager Puerta humana: el manager aprueba o rechaza la comanda antes de que llegue a cocina.
Chat híbrido Motor de conversación que combina lógica determinista (pedidos, alérgenos, precios desde BD) con un LLM que solo humaniza la respuesta.

Flujo end-to-end

El recorrido completo de un pedido, desde que el cliente se sienta hasta que paga:

flowchart TD
    A[Cliente escanea QR en la mesa] --> B[Se abre TableSession]
    B --> C[Chat con la IA<br/>texto o voz]
    C --> D[Se crea / actualiza una Comanda<br/>estado DRAFT]
    D --> E[Validación IA<br/>AI_REVIEWING]
    E -->|acepta| F[Aprobación del manager<br/>PENDING_MANAGER]
    E -->|rechaza| C
    F -->|aprueba| G[Cocina<br/>PENDING -> IN_PROGRESS -> READY]
    F -->|rechaza| C
    G --> H[Servir<br/>SERVED]
    H --> I[Pagar<br/>CLOSED]

Paso a paso:

  1. Escaneo del QR. El cliente abre la web (sin instalar nada) escaneando el QR de su mesa. Esto identifica el restaurante y la mesa.
  2. Apertura de sesión (TableSession). Se valida/crea la sesión de la mesa, que acompaña al cliente durante toda su visita. Ver Sesiones y carrito.
  3. Chat con la IA. El cliente conversa con el camarero virtual. El bot puede abrir la conversación de forma proactiva (saludo + pregunta de alergias). Ver Chat híbrido.
  4. Creación de la comanda. El pedido se materializa en una Comanda en estado DRAFT, con sus líneas, extras y comentarios. Ver Comanda.
  5. Validación IA (AI_REVIEWING). Al enviar la comanda, la IA la revisa. Si la acepta pasa a PENDING_MANAGER; si la rechaza (AI_REJECTED), el cliente la corrige.
  6. Aprobación del manager (PENDING_MANAGER). El manager aprueba (PENDING) o rechaza (MANAGER_REJECTED). Si el cliente edita una comanda que está esperando aprobación, esta vuelve a AI_REVIEWING y reinicia el ciclo completo.
  7. Cocina (PENDING → IN_PROGRESS → READY). Cocina toma la comanda, la prepara y la marca como lista.
  8. Servir (SERVED). El personal de sala entrega la comida a la mesa.
  9. Pagar (CLOSED). Se completa el pago y la comanda cierra. El total del ticket de la sesión es la suma de todas las comandas no canceladas. Ver Pagos.

Tiempo real con SSE

Cada cambio de estado se propaga en tiempo real mediante Server-Sent Events (SSE) tipados: el chat del cliente, el panel de cocina y el Control de sala del manager se actualizan sin recargar. Ver Tiempo real (SSE).

Ciclo de vida de la comanda

La comanda sigue una máquina de estados unificada que combina la puerta de IA, la puerta del manager y el ciclo de cocina:

DRAFT → AI_REVIEWING → PENDING_MANAGER → PENDING → IN_PROGRESS → READY → SERVED → CLOSED

Estados de rechazo y cancelación:

  • AI_REJECTED y MANAGER_REJECTED: el cliente puede editar y reenviar (vuelve a AI_REVIEWING).
  • CANCELED: cancelación en cualquier fase previa al servicio. Estado terminal.
  • CLOSED y CANCELED son estados terminales (sin salida).

Regla de edición durante la aprobación

Si el cliente modifica una comanda en PENDING_MANAGER (añade, cambia o quita una línea), la comanda vuelve a AI_REVIEWING y reinicia todo el ciclo de aprobación. Esto garantiza que la IA revalida y que el manager siempre ve la última versión.

El detalle completo (transiciones válidas, timestamps por transición, totales) está en Comanda.

Stack tecnológico

Capa Tecnología
Backend FastAPI · Python 3.12 · SQLAlchemy 2.x async · Alembic · Pydantic v2
Arquitectura backend Hexagonal / modular (app/modules/{m}/{domain,application,infrastructure,interface}) — ver Hexagonal (ADR-004)
Frontend Next.js · React · TypeScript · Tailwind CSS
Base de datos PostgreSQL (asyncpg), tanto en local como en producción
Tiempo real Server-Sent Events (SSE) tipados
IA Chat híbrido: clasificador de intents (embeddings) + handlers deterministas + LLM para redactar

Principios transversales del backend:

  • Multitenancy estricta: se filtra siempre por restaurant_id, verificado desde la autenticación o el path, nunca desde el body. Ver Seguridad y multitenancy.
  • Precios en céntimos (int): 12.50 € = 1250. Nunca floats en BD.
  • Multi-idioma (i18n): los campos name / description son diccionarios JSON ({"es": "...", "en": "..."}).
  • datetime siempre timezone-aware (UTC).
  • Contrato hacia el frontend: OpenAPI y eventos SSE están protegidos por tests contract-lock; las adiciones aditivas se permiten cableando el frontend en el mismo cambio. Ver Evolucionar el contrato.

Mapa de la documentación

Sección Para qué sirve
Empezar Poner en marcha el backend y el frontend en local.
Arquitectura Entender el diseño: hexagonal, SSE, sesiones y carrito, comanda, chat híbrido, control de sala, recomendador, pagos y seguridad.
Guías (how-to) Tareas concretas: ejecutar tests, migraciones de BD, añadir un módulo, evolucionar el contrato y desplegar.
Referencia Consulta detallada: API REST, eventos SSE, mapa de módulos, convenciones y configuración.
Contribuir Cómo trabajar en el proyecto, incluida una guía para LLMs.