Статусная модель заказа — текущее состояние

Статусная модель заказа — текущее состояние кода

Кратко (на одной странице)

Заказ в системе проходит один из трёх сценариев в зависимости от того, что в нём лежит и как он создан:

1. Быстрая продажа (за секунду)

Применяется когда: товар не требует кухни (бутылка воды, сигареты, упаковка кофе в зёрнах) и тип заказа takeaway.

Путь: new → closed в одной транзакции при вызове /internal/orders/checkout с POS.

Пример: кассир пробил бутылку воды → сразу оплачено → сразу закрыто. Кухня не трогается.

2. Кухонный / доставочный flow (основной)

Применяется когда: хотя бы один товар в заказе имеет requires_kitchen=true, либо заказ на доставку/в зал.

Полный путь: new → accepted → ready → handed_over → in_delivery → delivered → closed

• new — пробит, ждёт кухню
• accepted — кухня приняла, начали готовить (kitchen_started_at)
• ready — готово, ждёт выдачу/курьера
• handed_over — передан курьеру (только delivery)
• in_delivery — курьер везёт
• delivered — клиент получил
• closed — финализирован (для закрытия обязательно paid_at)

Для dine_in/takeaway с кухней доставочные статусы пропускаются: new → accepted → ready → closed.

3. Агрегаторский flow (Яндекс.Еда и т.п.)

Создаётся Aggregator Service’ом по вебхуку от маркетплейса. Идёт по той же доставочной цепочке, плюс каждый переход пушится обратно в агрегатор через Kafka order.status.changed.

Ключевые инварианты

• Paid ≠ Closed — оплата только ставит paid_at, закрытие требует отдельного /complete. Закрыть без paid_at нельзя (кроме legacy-записей).
• Cancel vs Refund — пока не оплачено можно cancel, после оплаты только refund.
• Редактировать состав заказа (добавить/удалить позиции, обновить коммент) можно только в new (или new/accepted/ready для dine-in add-items).
• Все переходы — строго по таблице «из → в»: невозможно прыгнуть из new в ready, минуя accepted.

События в Kafka

На каждый переход публикуется два сообщения: узкое (order.cooking_started, order.ready, order.handed_over, order.in_delivery, order.delivered, order.closed) + универсальное (order.status.changed). Универсальное используется Aggregator Service для проталкивания в маркетплейсы и для webhook-подписок внешних POS.

---

Подробный разбор

1. Все возможные статусы

Статус	Значение	Когда появился
new	Заказ создан, не начат	001-create-orders.xml
in_progress	Устаревший синоним accepted (остался для совместимости)	001
accepted	Кухня взяла в работу	005-add-aggregator-statuses.xml
ready	Готов, ожидает выдачу/курьера	001
handed_over	Передан курьеру	005
in_delivery	Курьер в пути	008-br-2-5-status-model.xml
delivered	Клиент получил	008
closed	Финализирован	001
cancelled	Отменён	001

CHECK-constraint в БД: CHECK (status IN ('new', 'accepted', 'ready', 'handed_over', 'in_delivery', 'delivered', 'closed', 'cancelled')) — источник: 008-br-2-5-status-model.xml:12-14.

Почему в списке нет in_progress

В коде и JWT встречается in_progress как legacy-значение (например kitchenQueuePage), но в текущем CHECK-constraint его нет. Это техдолг — название осталось в одном-двух местах UI, в БД новые записи имеют accepted.

2. State machine — полный список переходов

Из	В	Метод в OrderService	HTTP endpoint	Условие
new	closed	checkout()	POST /internal/orders/checkout	!requires_kitchen && takeaway (fast-checkout)
new	accepted	acceptAggregatorOrder()	POST /api/v1/orders/{id}/accept	channel != INTERNAL/POS
new	accepted	acceptAggregatorOrderInternal()	POST /internal/orders/{id}/aggregator/accept	service-token
new	accepted	startCookingInternal()	POST /internal/orders/{id}/start-cooking	kitchen trigger
new	cancelled	rejectAggregatorOrder()	POST /api/v1/orders/{id}/reject	новый заказ агрегатора
new	cancelled	cancel()	POST /api/v1/orders/{id}/cancel	paid_at IS NULL
new	closed	closeWithPayment()	POST /internal/orders/{id}/close-with-payment	dine-in split-pay
accepted	ready	markAggregatorOrderReady()	POST /api/v1/orders/{id}/ready	—
ready	handed_over	handOverAggregatorOrder()	POST /api/v1/orders/{id}/hand-over	—
ready	closed	complete()	POST /api/v1/orders/{id}/complete	paid_at IS NOT NULL
handed_over	in_delivery	startDelivery()	POST /api/v1/orders/{id}/start-delivery	permission orders.delivery
in_delivery	delivered	confirmDelivery()	POST /api/v1/orders/{id}/confirm-delivery	permission orders.delivery
delivered	closed	complete()	POST /api/v1/orders/{id}/complete	paid_at IS NOT NULL
* (кроме closed/cancelled)	cancelled	cancel()	POST /api/v1/orders/{id}/cancel	paid_at IS NULL

Основной код: OrderService.java — методы checkout(), pay(), complete(), cancel(), acceptAggregatorOrder(), markAggregatorOrderReady(), handOverAggregatorOrder(), startDelivery(), confirmDelivery(), transitionStatus().

Обобщённый хелпер transitionStatus(orderId, expected, target) в OrderService.java:564 — проверяет что текущий статус равен expected, иначе 422 INVALID_STATUS_TRANSITION.

stateDiagram-v2
    [*] --> new : checkout / create / openDineIn
    new --> closed : fast-checkout<br/>(!requires_kitchen && takeaway)
    new --> accepted : accept / start-cooking
    new --> cancelled : cancel / reject (до оплаты)
    accepted --> ready : ready
    ready --> handed_over : hand-over<br/>(только delivery)
    ready --> closed : complete<br/>(если paid_at != null)
    handed_over --> in_delivery : start-delivery<br/>(orders.delivery)
    in_delivery --> delivered : confirm-delivery<br/>(orders.delivery)
    delivered --> closed : complete
    closed --> [*]
    cancelled --> [*]

3. Инварианты (бизнес-правила, проверяемые кодом)

Инвариант	Где	HTTP-код при нарушении
Редактирование состава: status = 'new'	validateEditable()	422 ORDER_NOT_EDITABLE
Повторная оплата запрещена: payment_method IS NULL	pay()	422 ALREADY_PAID
Закрытие требует оплату: paid_at IS NOT NULL	complete()	422 ORDER_NOT_PAID
Закрытие только из ready или delivered	complete()	422 INVALID_STATUS_TRANSITION
Cancel требует paid_at IS NULL	cancel()	422 ORDER_ALREADY_PAID
Cancel нельзя из closed/cancelled	cancel()	422 INVALID_STATUS_TRANSITION
Reject только из new и только для агрегатора	rejectAggregatorOrder()	422 INVALID_STATUS_TRANSITION
Refund требует paid_at IS NOT NULL	createRefund()	422 ORDER_NOT_PAID
Сумма рефандов ≤ total	createRefund()	422 REFUND_EXCEEDS_TOTAL
add-items только для dine-in и только в new/accepted/ready	addItems()	409 CONFLICT
Переходы агрегаторского flow допустимы только для channel ∉ {INTERNAL, POS}	assertAggregatorOrder()	422 NOT_AGGREGATOR_ORDER
Доставочные переходы требуют permission orders.delivery	Auth middleware	403 FORBIDDEN

Ключевой инвариант BR 2.5: status='closed' ⇒ paid_at IS NOT NULL. Проверяется в сервисе (complete()), не в БД-CHECK — чтобы legacy-записи без paid_at не ломали систему.

4. Timestamps по статусам

Каждый переход ставит свой timestamp (так можно восстановить всю хронологию заказа):

Поле	Когда ставится	Кто ставит
created_at	Создание	@PrePersist
updated_at	Любое изменение	@PreUpdate
kitchen_started_at	Переход в accepted	acceptAggregatorOrder(), startCookingInternal()
accepted_at	Переход в accepted	acceptAggregatorOrder()
accepted_by	Переход в accepted	Записывает user_id кассира
ready_at	Переход в ready	markAggregatorOrderReady()
handed_over_at	Переход в handed_over	handOverAggregatorOrder()
in_delivery_at	Переход в in_delivery	startDelivery()
delivered_at	Переход в delivered	confirmDelivery()
paid_at	Оплата	pay(), checkout(), closeWithPayment()
completed_at	Закрытие	complete(), closeWithPayment()
cancelled_at	Отмена	cancel(), rejectAggregatorOrder()

Вся миграция BR 2.5 колонок: 008-br-2-5-status-model.xml:19-31.

5. Как определяется flow: флаг requires_kitchen

Момент расчёта: один раз при POST /internal/orders/checkout. После checkout’а флаг фиксируется в поле orders.requires_kitchen (boolean) и больше не меняется.

Алгоритм (OrderService.checkout()):

1. Собрать product_ids из позиций заказа
2. Вызвать GET /internal/products/require-kitchen?ids=<uuid1>,<uuid2> в Catalog Service
3. Ответ { "data": { "requires_kitchen": true|false } } — true если хотя бы один товар требует кухни
4. Записать в order.requires_kitchen
5. Если !requires_kitchen && order_type='takeaway' — закрыть заказ сразу (fast checkout)

При ошибке связи с Catalog Service возвращается false (best-effort, не блокируем checkout).

Источник: CatalogServiceClient.anyProductRequiresKitchen() + OrderService.checkout():234-258.

В самом Catalog: товар имеет два поля — requires_kitchen (boolean) и kitchen_station_id (FK на kitchen_stations). При requires_kitchen=true станция обязательна (валидация в ProductService).

6. Kafka-события — полный справочник

Публикатор: OrderEventPublisher.java.

Топик	Когда публикуется	Payload (ключевое)
order.created	Создан заказ	orderId, storeId, franchiseId, orderNumber, orderType, status, createdBy
order.paid	Оплата	orderId, total, paymentMethod, paidAmount, status
order.cooking_started	new → accepted	orderId, orderNumber, acceptedAt, acceptedBy
order.ready	accepted → ready	orderId, orderNumber, readyAt
order.handed_over	ready → handed_over	orderId, courierId, handedOverAt
order.in_delivery	handed_over → in_delivery	orderId, courierId, inDeliveryAt
order.delivered	in_delivery → delivered	orderId, customerId, courierId, deliveredAt
order.completed	* → closed (legacy alias)	orderId, customerId, total, status
order.closed	* → closed (BR 2.5 явный алиас)	Аналогично order.completed
order.cancelled	* → cancelled	orderId, cancelReason
order.refunded	Возврат	orderId, refundId, refundAmount, isFullRefund
order.status.changed	Каждый переход статуса	previous_status, new_status, channel, external_provider, reason

Два слоя событий — задумано не случайно:

• Узкие (order.cooking_started, order.delivered и т.д.) — для специализированных подписчиков, типизированный payload.
• Универсальное order.status.changed — для Aggregator Service (проталкивание статуса в Яндекс.Еду) и для webhook-подписок внешних POS/KDS. Можно подписаться один раз и получать все переходы.

7. Кто вызывает Order Service — матрица инициаторов

Инициатор	Создание заказа	Переходы статусов
POS касса	POST /internal/orders/checkout (быстрая продажа) или POST /internal/orders/open-dine-in (в зал)	close-with-payment, start-cooking, mark-ready, pay
Админка франшизы	Не создаёт заказы напрямую	Только агрегаторские: accept, ready, hand-over, reject. Для доставки: start-delivery, confirm-delivery (permission orders.delivery). Также cancel/refund-requests.
Aggregator Service	Из webhook Яндекс.Еды → публикует Kafka aggregator.order.received → Order Service создаёт запись	Слушает order.status.changed, ретранслирует в маркетплейс
Customer Service	Пока не создаёт заказы (не реализовано)	Слушает order.completed для пересчёта динамических групп CRM (BR 3.1)
Клиентский сайт / моб. приложение	Пока не подключено (в планах через Customer BFF)	—
Webhook-подписчики (внешние POS, KOALa)	Создают заказы через Order Service API	Получают все переходы через webhook-рассылку из Aggregator Service

8. UI-представление статусов (Админка Франшизы)

Названия бейджей (одинаковы на всех страницах: Active/History/Detail):

Статус	Русское название
new	Новый
in_progress	В работе
accepted	Принят
ready	Готов
handed_over	Передан курьеру
in_delivery	В доставке
delivered	Доставлен
closed	Закрыт
cancelled	Отменён

Цвета (токены бренда Альфы, web/src/lib/tokens.ts):

Статус	Цвет фона / текста
new	redSoft / red
in_progress	bgSoft / warning
accepted	redSoft / red
ready / handed_over / in_delivery / delivered	bgSoft / success
closed	border / text
cancelled	redSoft / red

Страницы:

• /orders/active — активные (new, in_progress, accepted, ready), автообновление каждые 30с
• /orders/history — закрытые/отменённые/переданные, с пагинацией и фильтром по дате
• /orders/:id — карточка заказа с действиями для агрегаторских (Принять/Готов/Передать/Отклонить) и для доставочных (Начать доставку/Подтвердить доставку)
• /kitchen/queue — канбан-доска для кухни (колонки new / accepted / ready)
• /catalog/kitchen-stations — управление кухонными станциями (BR 2.5)

9. Чего сейчас нет (технический долг / следующие фазы)

• Item-level статусы — сейчас статус на весь заказ, а не на позицию. Для KDS в будущем потребуется отдельный статус на каждой order_item.
• KDS как отдельное приложение — кухонный экран пока часть админки (KitchenQueuePage). Полноценный KDS вынесут в отдельный фронт.
• Split-payment по стульям — при dine_in с несколькими гостями нельзя разделить оплату по конкретным позициям.
• Автозакрытие по таймеру — в Yuma есть настройка «закрыть заказ через N минут, если клиент не пришёл».
• Кухонный принтер (ESC/POS) — не реализовано.
• Клиентский канал создания заказа (Customer BFF) — сервис слушает события для CRM, но сам не создаёт заказы.
• Item-level status (pending / cooking / done) — для гранулярного KDS.

10. Ссылки на ключевые файлы

Order Service (erp-order-service):

• Логика переходов: src/main/java/com/erp/order/service/OrderService.java
• Публичный API: src/main/java/com/erp/order/controller/OrderController.java
• Internal API: src/main/java/com/erp/order/controller/InternalOrderController.java
• Kafka: src/main/java/com/erp/order/event/OrderEventPublisher.java, OrderEventPayloads.java
• Клиент Catalog: src/main/java/com/erp/order/client/CatalogServiceClient.java
• Entity: src/main/java/com/erp/order/entity/Order.java
• Миграции: src/main/resources/db/changelog/001-create-orders.xml, 005-add-aggregator-statuses.xml, 008-br-2-5-status-model.xml

Aggregator Service (erp-aggregator-service):

• Приём заказов от маркетплейсов: service/OrderReceptionService.java
• Проталкивание статусов назад: service/StatusChangedConsumer.java + StatusPushWorker.java
• Webhook-диспетчер (BR 2.5): service/WebhookDispatcher.java, WebhookDeliveryWorker.java

Customer Service (erp-customer-service):

• Слушатель завершений: event/OrderCompletedConsumer.java
• Клиент статистики: client/CustomerOrderStatsClient.java

Admin (erp-admin):

• BFF-прокси: bff/src/routes/orders.ts
• Страницы: web/src/pages/orders/*.tsx, web/src/pages/kitchen/KitchenQueuePage.tsx, web/src/pages/catalog/KitchenStationsPage.tsx

POS (erp-pos):

• BFF: bff/src/routes/orders.ts
• Мобильный экран чека: mobile/src/screens/OrderSummaryScreen.tsx

Ссылки на спеки и BR

• Бизнес-спека: Заказы
• Бизнес-спека: Кухонные станции
• Бизнес-спека: Webhook-подписки
• Order Service API
• Order Service Data Model
• Order Service Events
• BR 2.5
• BR 2.3 (research)