Создание заказа через API: транзакция, ответ и внешние события
Область: ShariX Open, проверенный API-путь. Основание: опубликованные backend/tickets/webapp исходники от 29.10.2026. Фактический серверный сценарий этим source-анализом не выполнен.
Участники и предусловия
Интегратор или клиент вызывает POST /dbsynce/api/v1/orders/ установленной сборки ShariX Open. Маршрут создаётся в root core/urls.py → dbsynce.urls → apiviews/open_api.py при включённом DBSYNCE_OPEN_API_ENABLED. Не переносить этот endpoint автоматически на Platform.
OpenAPIBaseView допускает authenticated user либо HasAPIKey. Но создание использует request.user и предметные проверки заказчика/объектов: API key не является универсальной заменой actor. Инициатор должен иметь разрешённые основание заказа, тариф и связанные сущности. Self-order и корпоративный заказ имеют разные проверки; self-order нельзя одновременно оформить от организации.
Последовательность операции
create_order_from_payload внутри transaction.atomic нормализует режим draft/place, self-order и доступные сущности. Проверяет заказчика, получателя/его снимок, время, количество, длительность и маршрут. Отсутствующий тариф или недоступное сочетание не обходят подбором произвольного ID.
Создаётся Orders. Сохранённый order.pk назначает БД; чтение последней строки для вычисления нового ID не используется.
Создаётся SERVICE_REQUEST Ticket: draft → TEMPLATE, place → BOOKED. Subscription-category принудительно создаётся как place; её entitlement нельзя отложить до произвольного будущего размещения.
Ticket связывается с заказом; вызывается initialize_order_execution через зарегистрированный integration port. Наличие этого вызова не доказывает одинаковый набор Stage у всех сервисов.
При place и заданном исполнителе вызывается ACTION_ASSIGN_CREATED. Отказ назначения добавляет предупреждение, а не обязательно отменяет созданный заказ. В частности, конфликт занятого исполнителя или незавершённые требования отличают запись заказа от успешного назначения.
Внутри операции планируются события; после commit выполняются callbacks. Ticket wakeup — ticket.changed, а при каноническом переходе прежний owner получает ticket.moved. schedule_order_mobile_event перечитывает сохранённый заказ и предпринимает доставку мобильного события; транспортный отказ не равен откату уже committed заказа.
HTTP view получает snapshot по order.pk и возвращает 201, success, message, warnings и order. Проверяется содержимое warnings и фактическое состояние, а не один код ответа.
BPMN: границы транзакции и ответа
Описательная схема isExecutable=false. Свёрнутый task создания раскрыт шагами выше; схема не является runtime-кодом и не заменяет Blockly алгоритмы последующих обработчиков.
Django ValidationError преобразуется view в 400, PermissionDenied — в 403. Исключение внутри atomic до commit отменяет её записи. Но callback после commit — другая граница: данные уже сохранены. Не объявлять атомарность БД гарантией exactly-once доставки сети или rollback внешних систем.
Неизвестный creation_mode вызывает ValueError, который эта view явно не ловит. Это зафиксированное ограничение, а не готовый исправленный ответ 400. Серверные ошибки также не следует описывать как обязательный отказ валидации.
Если клиент не получил ответ на POST, повторная отправка может создать второй заказ: в изученной операции не найден отдельный контракт client idempotency key. Сначала установить результат по доступным записям/истории и контексту запроса. Нельзя вычислить успех по максимальному ID или отправить создание ещё раз только из-за таймаута.
HTML-форма — отдельный путь
sharix_admin.views.order.OrderCreateView.form_valid не вызывает целиком create_order_from_payload: она собирает модель через OrderForm и выполняет собственный atomic блок, используя общие ticket/action/execution primitives. У неё есть дополнительные subscription/extension шаги. Поэтому изменение только API не доказывает исправление формы, и наоборот. Согласованность этих путей проверяют отдельными сценариями; не переписывают документацию так, будто общей orchestration уже достаточно.
Проверка при изменении
На предназначенной тестовой установке проверить допустимое создание и доступность snapshot; draft и place; запрет чужих объектов/корпоративного контекста; self-order; отказ назначения с сохранением заказа и предупреждением; rollback при ошибке execution; событие только после commit. HTTP-ошибки проверить отдельно, включая неизвестный mode. Для HTML повторить затронутый form-сценарий. Чтение чужого заказа и запись зеркальных полей через local endpoint не должны становиться обходным путём; известное расхождение OrdersLocal/order_synced описано отдельно.
Эта матрица — порядок приёмки изменения, не отчёт о якобы выполненных здесь runtime-тестах.
Проверены опубликованные исходники указанных ревизий. Это source-анализ; он не подтверждает применённую версию, конфигурацию или успешный сценарий конкретного сервера.
