Назначение: Контракт. Продукт: ShariX Open · Общий компонент.

Для кого: Разработчик · Интегратор · Рецензент и приёмщик · Нейросеть.

Темы: API → Контракты · Заказы → Создание и черновик · Доступ → Объектные права.

Контракт API описывает:

• какое действие можно запросить;
• кто имеет право его выполнить;
• какие данные нужны;
• какой результат возвращается;
• какие возможны ошибки;
• какие данные меняются;
• какие внешние сообщения отправляются.

Одного адреса endpoint для этого недостаточно.

Открытый модуль может предоставлять точку расширения для закрытого компонента. Здесь описывают публичную сторону: входные данные, допустимый вызов, результат и отказы открытого ядра. Имена внутренних моделей, обработчиков и порядок установки закрытого компонента в эту страницу не переносят.

Слово shared означает совместное использование модуля, а не открытую лицензию. В установке ShariX Open могут присутствовать отдельно лицензируемые закрытые компоненты. Их внутренние модели, алгоритмы и инструкции описываются в intrawiki. Публичная Wiki обозначает только название и границу; за деталями и согласованием доступа обращаются к ответственным со стороны Platform.

Для анализа открытого API не нужен доступ к внутреннему коду такого компонента. Требование к его стороне передают ответственному; саму проверку и внутренние детали фиксируют в intrawiki. Лицензионная граница — владение моделями.

1. Найти маршрут в core/urls.py и urls.py нужного приложения.
2. Прочитать view и используемую форму или serializer: методы, входные поля и первоначальный допуск.
3. Найти функцию бизнес-операции: проверку пользователя, конкретного объекта и текущего состояния.
4. Проследить сохранение моделей, транзакцию, события и внешнюю доставку.
5. Найти HTML, мобильные и другие вызовы этой операции и относящиеся к ним проверки.

Названия и количество входов могут различаться. Похожее имя router и специализированного API ещё не означает одинаковый порядок создания и изменения объекта.

В ShariX Open маршрут /dbsynce/api/v1/orders/ ведёт к OpenOrderListCreateAPIView. Его POST вызывает dbsynce.lib.open_order_api.create_order_from_payload. Подключение маршрутов зависит от URL-конфигурации сборки и DBSYNCE_OPEN_API_ENABLED.

Полная последовательность описана в сценарии создания заказа. ID получают после сохранения; вычисление «последний ID плюс один» не является допустимым алгоритмом конкурентного создания.

Ответственность за данные разделяется так:

• Общие Order/Ticket изменяются через свои операции.
• Stage, Artifact и данные исполнения находятся у модуля исполнения; ради них не добавляют все локальные поля в Orders.

Подробнее — владение моделями.

OrdersLocalSerializer явно запрещает передачу перечисленных зеркальных полей общего заказа, даже если они обозначены read-only. Изменение локальных данных не является обходным способом сменить общего клиента, исполнителя или статус. У текущего локального endpoint есть расхождение order/order_synced, описанное в Webservice Running; защита полей сама его не устраняет.

При изменении контракта записать:

• маршрут и метод;
• поля запроса и ответа;
• проверку пользователя и объекта;
• идентификаторы;
• возможные отказы;
• побочные действия.

Затем проверить фактические места вызова и совместимость прежних данных. Внутри приложения разрешено переиспользовать опубликованную функцию другого модуля, сохраняя его ответственность за данные.

Стабильность API, форматов обмена, MENU_ALG, идентификаторов Ticket и алгоритма обработчика учитывают для всех публичных потребителей. Для общего модуля после публикации действует передача ответственному Platform. Его проверка, тестирование и принятие выполняются по intrawiki; внутренний порядок Platform здесь не описывается.

Отдельно проверяются:

• успешное сохранение БД;
• выполнение внешнего действия;
• доставка уведомления.

transaction.atomic не создаёт ключ идемпотентности сетевого запроса. Если ответ на POST потерян, сначала выясняют, что уже записано; безусловный повтор может создать второй объект.

Тестовый режим или пропуск внешнего вызова не должен выдавать сообщение об успешно выполненном внешнем действии. Настройку внешнего подключения рассматривают по публичному контракту модуля, не по внутреннему устройству другого продукта.

Текущая обработка ошибок этого POST:

• PermissionDenied преобразуется в HTTP 403.
• Django ValidationError преобразуется в HTTP 400.
• Неизвестный creation_mode в normalize_order_creation_mode вызывает ValueError, который эта view явно не ловит. Поэтому для такого ввода нельзя обещать HTTP 400.

Если этот случай входит в задачу, нужны отдельное исправление и отрицательная проверка.

Проверены опубликованные исходники указанных ревизий. Это source-анализ; он не подтверждает применённую версию, конфигурацию или успешный сценарий конкретного сервера.

• sharix-open-backend: models/orders.py — 778a3280cee1.
• sharix-open-backend: lib/open_order_api.py — 778a3280cee1.
• sharix-open-backend: lib/ticket_gen.py — 778a3280cee1.
• sharix-open-backend: lib/order_actions.py — 778a3280cee1.
• sharix-open-backend: lib/order_permissions.py — 778a3280cee1.
• sharix-open-backend: lib/mobile_order_events.py — 778a3280cee1.
• sharix-open-backend: lib/integration_ports.py — 778a3280cee1.
• sharix-open-backend: apiviews/open_api.py — 778a3280cee1.
• sharix-open-backend: urls.py — 778a3280cee1.
• sharix-open-webservice-running: apiviews/orders_local.py — d5b966a88b2d.
• sharix-open-webservice-running: serializer/orders_local.py — d5b966a88b2d.

• sharix-open-backend: apiviews/open_api.py.
• sharix-open-backend: lib/open_order_api.py.
• sharix-open-backend: lib/order_permissions.py.
• sharix-open-backend: urls.py.
• sharix-open-webapp-base: core/urls.py.

Статус: согласовано, поставлено в очередь API-001 / SYNC-001; это не объявление готового исправления.

Если активация категории заблокирована нарушенной синхронизацией или lifecycle Сервиса на Platform, ответ API должен явно сообщать эту причину. Не ограничиваться общим HTTP 403 или can_submit=false. Требуются стабильный код причины, безопасное объяснение, фактический статус Platform и идентификатор диагностики; при наличии — отдельное состояние sync и разрешённый следующий шаг. Точный HTTP-код/формат уточняются при реализации, без изменения существующего мобильного контракта.

Различать права пользователя, бизнес-согласование категории, lifecycle Сервиса, техническую ошибку синхронизации и недоступность Platform. ShariX Open передаёт допустимую структурированную причину от владельца решения, сохраняя границы модулей; ключи и сырые ошибки не возвращаются. HTTP 200 у контрольного status-запроса подтверждает чтение ответа, а не право активации категории. Локально сохранённый active и фактический lifecycle Platform могут различаться; это различие должно быть видно клиенту.

После успешной синхронизации lifecycle не должен оставаться в ошибке, вызванной этой синхронизацией, если нет иных явных препятствий. Успех импорта не одобряет изменённую редакцию Сервиса, не отменяет отключение/удаление или отдельное административное решение. При таком препятствии возвращать его явную причину. Не считать старый last_success_at доказательством текущего успешного восстановления и не стирать происхождение ошибки до завершения согласованного восстановления.

Чтение диагностики не меняет lifecycle и не создаёт заявку. Выполнение требований и приёмка конкретных установок подтверждаются отдельно.

01.11.2026, SYNC-002 / APPR-001: согласовано; пока анализ и очередь изменений, без внедрения. Это уточнение определяет целевое поведение и дополняет описанный выше разбор текущей реализации.

Временная недоступность, таймаут, перезапуск и переключение production/testing должны отражаться как технический режим обслуживания, сохраняя действующее бизнес-согласование. После восстановления связи и успешной синхронизации обслуживание завершается автоматически; новая бизнес-активация только ради возврата связи не требуется. Не смешивать бизнес-допуск, подтверждённую редакцию данных, доступность и состояние выполнения sync.

При переключении профиля другая Platform должна видеть обслуживание своей связи, а не сломанную интеграцию или отзыв согласования. Возврат в профиль не требует повторного согласования без отдельного существенного события. Состояния, credentials, идентификаторы, cursor/ack и callbacks разных профилей должны оставаться изолированными; невыбранный профиль не получает данные namespace выбранного. Проверки ключа и предметных прав сохраняются. Протокол обслуживания, допустимые операции в нём и additive-совместимость со старым мобильным API ещё проектируются.

Согласование снимается только явным наступлением события, которое предусматривает такой отзыв. Это может быть изменение согласуемых критически важных данных/редакции либо явное решение уполномоченного участника; каталог полей и иных существенных оснований подлежит сверке с существующими domain owners. Потеря связи, таймаут, backoff и переключение профиля сами по себе такими событиями не являются.

Для отзыва сохраняются основание, источник/инициатор, время, область и затронутая согласованная редакция. Поздний callback и повтор события не должны отменять решение другой редакции. Восстановленная связь снимает техническое обслуживание, но не отменяет действительный отзыв, отключение/удаление или иное явное бизнес-препятствие.

Требование API-001 сохраняется: если maintenance/синхронизация блокируют действие с категорией, ответ сервера явно показывает причину и различает её с отсутствием согласования или прав. Применение этих требований и приёмка конкретных установок пока не подтверждены.