Procesar jobs KDS automáticamente
Con el KDS abierto en Marea Gran Via, una sesión de servicio activa, terminal local válida y permisos de operación, Antylogic consume en segundo plano jobs `kds` que ya existen en `tpv_output_jobs`. La terminal reclama cada job, ejecuta `kds_local` y deja el resultado como `completed` o `failed`; la revisión operativa se hace desde la cola TPV de impresión y KDS.
En este artículo
Esta guía explica el comportamiento real del procesamiento KDS: no hay un botón visible para ejecutar jobs, porque el runtime local trabaja mientras el tablero KDS está abierto y enfocado.
Úsala para comprobar qué condiciones debe tener la ubicación, cómo se reclama un job KDS y dónde revisar si terminó correctamente o quedó fallido.
Antes de empezar
- Usuario autenticado en Grupo Marea Demo con la ubicación Marea Gran Via seleccionada.
- KDS activo en ajustes TPV mediante `tpv_settings.enable_kds`.
- Permiso `kds:use` o `kds:manage` para procesar jobs; `kds:view` solo permite consultar la pantalla.
- Sesión de servicio activa en la ubicación.
- Terminal local activa en `tpv_terminals`; el `terminalId` de la URL no sustituye esa terminal local.
- Dispositivo de salida KDS activo ya provisionado.
- Al menos un `tpv_output_job` existente con `job_kind == "kds"`, asociado al servicio activo, al dispositivo KDS y a la terminal seleccionada.
Instrucciones
- 1.
Abrir el KDS de la ubicación
Abre `/:orgId/:locationId/kds?terminalId=:terminalId`. La pantalla valida organización, ubicación, permisos KDS y que `enable_kds` esté activo antes de cargar el tablero.
- 2.
Mantener una sesión de servicio activa
KDS solo consulta la cola cuando existe `activeSession.id`. Con el servicio activo, la pantalla consulta periódicamente `tpv_output_jobs` del servicio mientras permanece enfocada.
- 3.
Dejar que la terminal filtre la cola
El runtime usa la terminal local activa y solo toma jobs `kds` asignados o reclamados por esa terminal. También exige que el job apunte a un dispositivo KDS activo.
- 4.
Procesar el job en segundo plano
Si el job está `pending`, la terminal lo actualiza a `claimed` con trazabilidad en `terminal_id`, `claimed_by_terminal_id` y `payload.runtime`. Después ejecuta el adaptador local `kds_local`.
- 5.
Revisar el resultado en TPV
Cuando el adaptador termina, KDS intenta cerrar el job como `completed`; si falla, lo marca como `failed` con mensaje de error. El operador revisa el estado en `/:orgId/:locationId/tpv?tab=floor&terminalId=:terminalId`, dentro de la cola de impresión y KDS.
Validaciones y límites
- `kds:view` permite abrir la pantalla, pero no activa el procesamiento automático.
- Sin `activeSession.id`, KDS no habilita la consulta de `tpv_output_jobs`.
- La pantalla solo pasa al runtime dispositivos activos con `device_kind == "kds"` o `driver_kind == "kds"`.
- Con terminal seleccionada, el job debe coincidir con `terminal_id` o `claimed_by_terminal_id`.
- El runtime omite jobs `completed`, `cancelled` y `failed`, y evita procesar dos veces en paralelo el mismo `id`.
- La acción consume jobs ya existentes; no crea `tpv_output_jobs` desde el tablero KDS.
- El backend valida ubicación, pertenencia del job, terminal enviada, `status` permitido y `payload` JSON.
- Los jobs `failed` no se reintentan automáticamente desde KDS; se revisan y recuperan desde acciones de TPV.
Resultado esperado
La terminal local deja evidencia en `tpv_output_jobs`: `claimed` durante la ejecución y después `completed` o `failed`. La confirmación visible para el operador está en la cola TPV de impresión y KDS, no como una confirmación individual dentro del tablero KDS.