Назначение: Контракт. Продукт: 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.