Cómo avanzar un producto en KDS
Mueve un producto visible del tablero KDS al siguiente estado de producción con un swipe izquierdo sobre su fila. La acción actualiza solo ese `ticket_item`, refresca el tablero y no cambia importes, pagos ni el estado general del ticket.
En este artículo
Usa esta guía cuando cocina necesite marcar el progreso de un producto durante un servicio activo en Marea Gran Via o en la ubicación operativa equivalente.
El avance se hace desde el tablero KDS, no desde el detalle TPV: el operador localiza una fila visible, la desliza hacia la izquierda y confirma el cambio en la propia vista de cocina.
Antes de empezar
- Trabajar con una organización y ubicación seleccionadas; en la demo ES, Grupo Marea Demo / Marea Gran Via.
- Abrir `/:orgId/:locationId/kds?terminalId=:terminalId` con el terminal de la demo cuando aplique.
- Tener `tpv_settings.enable_kds` activo y una `service_session` abierta para la ubicación.
- Tener permiso operativo `kds:use` o `kds:manage`; `kds:view` permite consultar el tablero, pero no operar filas.
- Contar con un ticket abierto, no `closed` ni `void`, con al menos un producto de cocina visible en `draft`, `sent`, `preparing` o `ready`.
- Para que un producto en `draft` aparezca en KDS debe tener `requires_kitchen === true`; los productos en `sent`, `preparing` o `ready` ya forman parte del flujo KDS.
Instrucciones
- 1.
Abrir el tablero KDS
Entra en KDS para la ubicación activa. La pantalla comprueba permisos, carga los ajustes TPV, valida que KDS esté habilitado y busca la sesión de servicio activa antes de mostrar productos pendientes de cocina.
- 2.
Localizar el producto
Busca una fila visible en `draft`, `sent`, `preparing` o `ready`. KDS excluye tickets cerrados o anulados y deja fuera del tablero operativo los productos `served` y `cancelled`.
- 3.
Deslizar hacia la izquierda
Desliza la fila del producto hacia la izquierda. El gesto avanza una sola línea siguiendo la secuencia `draft -> sent -> preparing -> ready -> served` y bloquea temporalmente esa fila mientras se guarda el cambio.
- 4.
Comprobar el resultado
Espera al refresco del tablero. El producto pasa a la siguiente columna o desaparece si el destino es `served`. El ticket mantiene sus importes, pagos y estado general.
Validaciones y límites
- Si falta la ubicación, KDS muestra `Selecciona una ubicación para abrir cocina.`
- Sin permisos KDS, la pantalla muestra `No tienes permisos para usar KDS.`
- Si KDS está deshabilitado, se muestra `KDS está deshabilitado en los ajustes del TPV.`
- Con solo `kds:view`, el tablero es consultivo y la fila queda no operable.
- La operación envía el estado visto en pantalla como protección: si otro terminal ya cambió el producto, el backend no pisa ese cambio y devuelve el ticket actualizado.
- El backend valida que el ticket pertenezca a la ubicación, que no esté `void`, que `to_status` sea válido y que los `item_ids` existan en ese ticket.
- Un producto sin flujo de cocina no puede moverse explícitamente a `sent`, `preparing` o `ready`.
- Al avanzar de `draft` a `sent` desde KDS, la UI envía `suppress_output: true`; esta acción concreta no genera jobs de salida de cocina.
Resultado esperado
El producto queda actualizado en `ticket_items.production_status` y el tablero KDS se sincroniza con el ticket devuelto. La acción afecta una única fila, no recalcula importes, no modifica pagos y no cambia por sí misma `tickets.status`.