Задачи подачи

Задача подачи — это один физический рейс: отнести поднос с этим заказом к этому столу или отвезти этот заказ по адресу доставки. Задачи предлагаются Sitora, принимаются вашим контроллером и ведутся по строгой машине состояний.

Жизненный цикл

offered ──claim──▶ claimed ──сотрудник загружает──▶ loaded ──▶ en_route ──▶ arrived ──▶ completed
   │                  │                                                │
   └─ expired         └─ failed(code) ◀────────────────────────────────┘  в любой момент: cancelled

`offered → claimed`

POST /serving-tasks/{id}/claim/. Побеждает первая заявка; проигранная гонка возвращает 409 с кодом already_claimed; истёкшее окно предложения возвращает 410 с кодом offer_expired. Истёкшие предложения возвращаются людям — не считайте истечение ошибкой для повтора.

`claimed → loaded` подтверждается сотрудником

Ваш робот ждёт у раздачи; человек подтверждает в Sitora Pro, что поднос соответствует манифесту. Вы не можете сообщить loaded — попытка вернёт 400 с кодом status_not_reportable. Ответственность за еду передаёт человек, машина не объявляет её сама.

`loaded → en_route → arrived → completed`

POST /serving-tasks/{id}/report/ с {"status": "..."}. Отчёты строго упорядочены; отчёт не по порядку возвращает 409 с кодом task_<текущий_статус> (например task_claimed) и пояснением с текущим состоянием задачи. К любому отчёту можно приложить необязательный объект telemetry; он сохраняется в журнале событий задачи.

`failed`

Сообщается из любого состояния после принятия, с кодированной причиной:

`failure_code`	Значение
`obstacle_blocked`	Путь заблокирован без возможности восстановления.
`hardware_fault`	Механическая или электрическая неисправность.
`navigation_lost`	Потеряна локализация.
`payload_disturbed`	Поднос или груз нарушен в пути.
`battery_critical`	Недостаточно заряда для завершения рейса.
`operator_abort`	Вмешался ваш оператор.
`other`	Что-то иное — укажите `reason`.

Сбой безопасен: заказ мгновенно возвращается в человеческий процесс, а сотрудники получают оповещение. Сообщайте о сбоях честно и сразу.

`cancelled`

Приходит от Sitora — сотрудник подал заказ первым, заказ был отменён или сотрудник отменил рейс. Остановите рейс и вернитесь на базу. Отмена после loaded оповещает сотрудников, чтобы забрать поднос.

Завершение и подтверждение

Завершение никогда не записывает статус заказа напрямую. Что произойдёт дальше, решает политика подтверждения филиала:

human_confirmed (по умолчанию) — сотрудники подают заказ в Sitora Pro как обычно; их подтверждение замыкает цикл и обратно связывается с задачей.
auto_confirm — бэкенд сам применяет переход заказа после вашего отчёта completed. Отчёт должен прийти не раньше настроенной задержки (auto_confirm_dwell_seconds в снимке парка) после arrived — завершение быстрее, чем гость мог бы правдоподобно забрать поднос, отклоняется с 409 (arrival_dwell_pending).

Манифест

Каждая задача несёт описание работы — и ничего больше:

{
  "order_display_number": 118,
  "leg": "dine_in_tray",
  "items": [
    { "name": "Grilled trout", "quantity": "1" },
    { "name": "Green tea", "quantity": "2" }
  ],
  "dining_spot": { "id": 12, "number": 4, "label": "Table 4", "spot_type": "table" }
}

Манифесты курьерского этапа вместо dining_spot несут delivery_address. Ни записи о госте, ни номера телефона, ни заметки к заказу, ни цены, ни платёжных данных там никогда нет — эти поля просто не читаются в манифест.

delivery_address — свободный текст, введённый гостем. Это точка назначения, которой ваш робот должен достичь, поэтому он раскрывается полностью — а на практике люди пишут в это поле больше, чем улицу: имя получателя, квартиру и код домофона, иногда номер для обратной связи. Считайте всё поле персональными данными. По контракту робототехники вы обязаны использовать его только для завершения текущего рейса, не хранить после перехода задачи в конечное состояние и не обрабатывать его для обогащения данных. Sitora по той же причине перестаёт отдавать манифест, как только задача достигает конечного состояния.

Манифест отдаётся только на эндпоинтах опроса, где ваши учётные данные проверяются при каждом чтении. Он никогда не отправляется в webhook.

Задачи подачи

Жизненный цикл

offered → claimed

claimed → loaded подтверждается сотрудником

loaded → en_route → arrived → completed

failed

cancelled