Saltar al contenido principal

Frihet Kitchen

Frihet Kitchen es la app vertical de hostelería sobre Frihet ERP. Combina un KDS (Kitchen Display System) por estación con toma de comandas en modalidad de cobro inmediato (pay_now), emisión fiscal directa en el libro del ERP, recuperación de tickets cerrados (Recall) y analítica operativa de tiempos de preparación.

Cómo funciona​

El módulo /kitchen organiza el servicio de cocina y barra en cinco vistas operativas conectadas en tiempo real sobre las colecciones del workspace:

  • /kitchen (orders.read): resumen operativo con accesos directos a comandas, tablero KDS y métricas del turno.
  • /kitchen/pos (orders.write): toma de comandas en modalidad de cobro inmediato (pay_now) con selector de modificadores (ModifierSelectionSheet), modalidad de servicio (dine-in, takeaway, delivery) y método de cobro (cash, card, external).
  • /kitchen/kds (kds.view / kds.bump): pantalla KDS filtrable por estación con flujo de estados queued (Pendiente) → preparing (En preparación) → ready (Listo) → served (Servido), consolidación de cantidades en preparación y cajón Recall para recuperar tickets de los últimos 30 días.
  • /kitchen/reports (analytics.view): panel de métricas de servicio con tickets activos (activeTickets), tiempo medio de preparación (avgPrepMinutes), tickets servidos (servedTickets), tasa de listos (readyRate%), carga por estación (stationLoad) y mix de estados (statusMix).
  • /kitchen/management (menu.read / menu.write): gestión del catálogo de cocina (fk_kitchenMenuItems) y de las estaciones de preparación (fk_kitchenStations) con sembrado inicial de estaciones base (seedDefaultStations: hot, cold, bar, expo).

La facturación de cada pedido viaja por el motor fiscal del ERP. Las ventas generan tickets simplificados (B2C) o facturas completas (B2B) y aplican IVA o IGIC según la zona. No hay duplicidad de datos: cada comanda cobrada genera su documento fiscal directamente en el libro registro del ERP (fiscalGateway).

El registro VeriFactu de la venta se envía automáticamente a la AEAT si activas Envío automático a AEAT y tienes un certificado digital válido configurado en Finanzas → Fiscal → Cumplimiento. Con Modo pruebas (sandbox) activo, que es el valor por defecto, el envío va al entorno de pruebas de la AEAT. VeriFactu también se aplica a los contribuyentes con domicilio fiscal en Canarias: la AEAT los incluye en el ámbito del RD 1007/2023 y entiende hechas al IGIC las referencias al IVA (preguntas frecuentes de la AEAT). Con la zona fiscal Canarias, el envío de los registros a la AEAT no está disponible en Frihet.

Alcance operativo actual en /kitchen

La gestión visual de plano de mesas (/kitchen/tables), las reservas de mesa y las cuentas abiertas (open_table), así como los conectores directos con agregadores de reparto (Glovo, Uber Eats) o los avisos automáticos por WhatsApp, no están habilitados en la superficie estándar actual de /kitchen. Los pedidos de reparto o para llevar se registran desde /kitchen/pos seleccionando orderType: 'delivery' o 'takeaway', y sus tiempos o prioridades de entrega pueden actualizarse mediante PATCH /v1/kitchen/tickets/:id indicando courierEtaMinutes. En @frihet/mcp-server 1.17.0, esa misma actualización de estado, prioridad o ETA de repartidor se realiza con la herramienta MCP update_kitchen_ticket (api_dependent).

Configuración​

Activa la app desde Ajustes → Frihet Apps (tarjeta Kitchen) en tu cuenta de Frihet ERP. La app está integrada con Frihet POS — si gestionas restauración, normalmente activarás ambas. La activación incluye un periodo de prueba antes de pasar al plan suscrito.

Las estaciones de cocina (fk_kitchenStations) y los platos del menú con su estación asignada (fk_kitchenMenuItems) se configuran directamente desde /kitchen/management tras activar la aplicación.

Recorrido operativo: de configurar estaciones a comandar, marchar en KDS y revisar tiempos​

Este recorrido cubre un servicio completo en Frihet Kitchen para el mismo negocio sintético de referencia (Cafetería Puerto Norte S.L., NIF B12345674 — sintácticamente válido según el algoritmo oficial; el formato válido no acredita existencia en el censo de la AEAT — y correo caja@example.com — dominio reservado por IANA según RFC 6761 para documentación; no es un buzón de QA controlado ni una garantía de impedir envíos): sembrar las estaciones de trabajo, dar de alta platos por estación, comandar y cobrar un pedido en /kitchen/pos, marchar los platos en /kitchen/kds, usar Recall ante un cierre accidental y auditar los tiempos en /kitchen/reports.

Rol en KitchenPermisos asignados (KITCHEN_ENTITLEMENTS)Superficie operativa permitida
adminorders.read, orders.write, kds.view, kds.bump, menu.read, menu.write, analytics.viewAcceso completo a resumen, Kitchen POS, KDS, reportes y gestión de menú y estaciones.
managerorders.read, orders.write, kds.view, kds.bump, menu.read, menu.write, analytics.viewGestión operativa del turno, catálogo (fk_kitchenMenuItems), estaciones y analítica.
cheforders.read, kds.view, kds.bump, menu.readOperación del tablero /kitchen/kds, avance de estados por estación y recuperación en Recall.
waiterorders.read, orders.write, kds.view, menu.readToma de comandas y cobro inmediato en /kitchen/pos y consulta visual de /kitchen/kds.
viewerorders.read, kds.view, menu.readConsulta en solo lectura de pedidos, pantalla KDS y carta.

Paso 1: Sembrar estaciones y dar de alta platos en Gestión​

  1. Entra en /kitchen/management con un usuario admin o manager (permiso menu.write).
  2. Si el local no tiene estaciones creadas en fk_kitchenStations, pulsa Crear estaciones por defecto (seedDefaultStations). El sistema registra las 4 estaciones base ordenadas para el pase:
    • hot (Cocina caliente, orden 10),
    • cold (Partida fría / postres, orden 20),
    • bar (Barra y bebidas, orden 30),
    • expo (Pase / expedición, orden 40).
  3. En la sección de carta (fk_kitchenMenuItems), crea dos platos de ejemplo para Cafetería Puerto Norte S.L.:
    • Plato 1: Arroz meloso de setas — SKU: ARR-010, categoría Principales, estación hot, precio 16,50 €, available: true.
    • Plato 2: Tarta fría de queso — SKU: POS-020, categoría Postres, estación cold, precio 6,00 €, available: true.

Paso 2: Tomar comanda en Kitchen POS y enrutar a estaciones​

  1. Abre /kitchen/pos con rol waiter, manager o admin (orders.write).
  2. Selecciona 1 × Arroz meloso de setas (16,50 €) y 1 × Tarta fría de queso (6,00 €) por un total de 22,50 €. Si el plato incluye variantes o notas de preparación (por ejemplo, punto de cocción o alérgenos), configúralas en el panel ModifierSelectionSheet.
  3. Completa los metadatos operativos del pedido antes de confirmar:
    • Etiqueta de mesa o referencia (tableLabel): "Mesa 4".
    • Modalidad de pedido (orderType): "dine-in" (sala), "takeaway" (recogida en local) o "delivery" (reparto).
    • Método de cobro (paymentMethod en modalidad pay_now): "card" (admite cash | card | external).
  4. Resultado verificable tras confirmar: Kitchen invoca fiscalGateway para emitir el documento fiscal en el ERP (fiscalInvoiceId, fiscalStatus: 'issued') y registra el ticket en fk_kitchenTickets con estado inicial queued, desglosando sus líneas en fk_kitchenTicketItems hacia las estaciones hot (Arroz meloso de setas) y cold (Tarta fría de queso).

Paso 3: Operar el KDS por estación, usar Recall y auditar el servicio​

  1. Filtrado y consolidación en /kitchen/kds (kds.view / kds.bump):
    • Selecciona el filtro de estación (all, hot, cold, bar, expo). En la barra superior, el KDS muestra el contador consolidado de unidades activas en preparación para agrupar marchas idénticas.
  2. Avance de estados (bump):
    • Avanza cada línea o el ticket completo de "Mesa 4" por las columnas del tablero: queued (Pendiente) → preparing (En preparación) → ready (Listo) → served (Servido).
    • Al marcar el ticket como served, el servidor sella las marcas de auditoría completedAt, bumpedBy y bumpedAt.
  3. Recuperación de tickets cerrados (cajón Recall):
    • Si un cocinero o encargado marca por error el ticket de "Mesa 4" como served o voided, pulsa Recuperar tickets (Recall) en /kitchen/kds.
    • El cajón consulta los tickets de los últimos 30 días en fk_kitchenTickets ordenados por createdAt desc y permite restituir el ticket seleccionado al estado ready.
  4. Cierre y auditoría del servicio en /kitchen/reports (analytics.view), API REST v1 y MCP:
    • En /kitchen/reports, revisa las 4 tarjetas principales (activeTickets, avgPrepMinutes, servedTickets, readyRate%), la tabla de carga por estación (stationLoad) y el desglose por estado (statusMix).
    • API REST v1: consulta o integra el flujo con GET /v1/kitchen/tickets, GET /v1/kitchen/stations, GET /v1/kitchen/menu-items y PATCH /v1/kitchen/tickets/:id.
    • Servidor @frihet/mcp-server 1.17.0: las 6 herramientas MCP del dominio Kitchen (list_kitchen_tickets, get_kitchen_ticket, update_kitchen_ticket, list_kitchen_stations, list_menu_items, kitchen_flow_summary, todas con api_dependent) exponen el estado de comandas, estaciones y métricas de flujo a tus agentes.

Recuperación ante incidencias operativas en Kitchen​

Incidencia durante el servicioEstado o campo afectadoAcción de recuperación verificada
Pedido retenido en cocina o con retraso de repartidorstatus: 'on_hold', holdReason (máx. 140 caracteres), priority: 'rush' o courierEtaMinutes (0–240)Envía PATCH /v1/kitchen/tickets/:id (o invoca update_kitchen_ticket) indicando status: 'on_hold' y el motivo en holdReason, o eleva la prioridad a priority: 'rush' actualizando courierEtaMinutes.
Ticket marcado como served o voided antes de entregar un platoTicket fuera de las columnas activas del tablero /kitchen/kdsAbre el cajón Recuperar tickets (Recall) en /kitchen/kds (historial de los últimos 30 días en fk_kitchenTickets ordenado por createdAt desc) y pulsa Recuperar para devolverlo al estado ready.
Fallo de emisión fiscal al comandar (fiscalStatus: 'failed')Ticket en fk_kitchenTickets sin fiscalInvoiceId válidoLocaliza el ticket con fiscalStatus: 'failed', verifica que el NIF/CIF, la dirección y la serie estén completos en Ajustes → Perfil Fiscal y Finanzas → Fiscal → Cumplimiento, y reintenta.

Ver también​