Cómo avanzar un item en KDS
Avanza un producto de cocina desde el tablero KDS con un gesto horizontal, manteniendo el estado sincronizado con el ticket y las salidas de cocina cuando correspondan.
En este artículo
El tablero KDS concentra los productos de cocina del servicio activo. Desde esa vista, el equipo puede mover cada item por la secuencia `draft` -> `sent` -> `preparing` -> `ready` -> `served` sin abrir formularios ni cambiar de pantalla.
En la demo de Grupo Marea Demo, el flujo se valida sobre Marea Gran Via con una cuenta abierta del servicio activo. Si el producto pasa a `sent`, Antylogic puede generar trabajos de salida `kitchen_order` para impresoras de cocina o dispositivos KDS activos.
Antes de empezar
- Trabajar con una organización y ubicación seleccionadas; en la demo, Grupo Marea Demo y Marea Gran Via.
- Tener KDS habilitado en los ajustes TPV de la ubicación (`tpv_settings.enable_kds`).
- Contar con una `service_session` activa; sin servicio activo, el tablero no carga cuentas operables.
- Tener permiso `kds:use` o `kds:manage` para operar. Con solo `kds:view`, el tablero puede verse, pero la fila no avanza.
- Usar un ticket abierto del servicio activo, no cerrado ni anulado, con al menos un item relevante para cocina.
- Elegir un item visible en `draft`, `sent`, `preparing` o `ready`; `served` y `cancelled` no aparecen en el tablero KDS.
Instrucciones
- 1.
Abre el tablero KDS
Entra en `/:orgId/:locationId/kds` o usa el deep link `antylogic://:orgId/:locationId/kds`. La pantalla debe mostrar el servicio activo de la ubicación antes de avanzar productos.
- 2.
Localiza el producto de cocina
Busca la cuenta, mesa o empleado y confirma que el item está dentro del flujo KDS. En la demo puede aparecer asociado al servicio de Marea Gran Via y al personal TPV como Marta Ruiz.
- 3.
Desliza la fila para avanzar
Haz un swipe horizontal sobre la fila del item hacia el lado de avance hasta revelar la acción del siguiente estado y suelta el gesto. El tablero calcula el siguiente paso con la secuencia `draft` -> `sent` -> `preparing` -> `ready` -> `served`.
- 4.
Espera el refresco del tablero
Cuando el backend devuelve el detalle actualizado del ticket, la vista refresca las consultas. El item cambia de estado, actualiza su temporizador o desaparece si ha pasado de `ready` a `served`.
- 5.
Revisa las salidas de cocina si aplica
Si el destino es `sent`, el sistema intenta crear jobs `kitchen_order` para los dispositivos de salida seleccionables. El avance del estado no depende de que existan esos dispositivos.
Validaciones y límites
- La pantalla KDS no es operable si `tpv_settings.enable_kds` está desactivado o si no hay `activeSession.id`.
- El cliente de la app usa `POST /api/app/{orgId}/{locationId}/tickets/{ticketId}/items/production-status`; `PUT` está soportado por backend como compatibilidad, pero no protagoniza el flujo de UI.
- La mutación envía `item_ids`, `from_statuses` y `to_status`; `from_statuses` protege el item frente a cambios hechos por otra terminal.
- Si el estado real ya no coincide con `from_statuses`, el backend devuelve el `TicketDetail` actual sin pisar el cambio concurrente.
- Un item en `draft` solo entra en flujo de cocina si requiere cocina; los items en `sent`, `preparing` o `ready` ya se consideran parte del KDS.
- Si la mutación falla, la UI limpia el estado de procesamiento y muestra el mensaje base: No pudimos actualizar el estado del producto.
- Cuando el destino es `sent`, los jobs de cocina solo se crean para los items actualizados y solo si hay impresoras de cocina o dispositivos KDS activos seleccionables.
Resultado esperado
El item queda sincronizado con el backend en el siguiente estado de producción. El tablero refleja el nuevo estado del ticket y, cuando corresponde, queda preparado el trabajo de salida de cocina para los dispositivos activos.