API и протокол команд

Фактическая спецификация — packages/api-contracts/openapi.json. Целевые операции графа — packages/journey-contracts/api-contracts.json. Их сопоставление и дополнения CRUD — packages/backend-atlas/atlas.json. Не зарегистрированные маршруты отсутствуют в фактическом OpenAPI, а в атласе имеют статус contract.

Общий контракт

Для private API нужен Authorization: Bearer <opaque-session-token>. Изменяющий запрос передаёт Idempotency-Key длиной 8–160 символов. Поля запросов заданы Pydantic; лишние поля, наивные даты и недопустимые суммы отвергаются. Клиент не передаёт роль или authoritative payment status. Ожидаемая версия объекта указывается в expected_revision.

Ошибка имеет envelope {error: {code, retryable, correlation_id, details}}. Валидация не возвращает введённые значения: токены, контактные данные и приватный текст не попадают в сообщение об ошибке. 401 — нет действующей сессии; 403 — нет capability; 404 — объект отсутствует или чужой; 409 — конфликт версии, времени, идемпотентности или состояния; 422 — неправильный запрос; 503 — БД или необходимая интеграция недоступна.

Списки возвращают items, next_cursor, as_of. Cursor — UUID последнего выданного объекта; limit ограничен 1–100. Это keyset pagination, не snapshot isolation между HTTP-запросами. Все ответы Cache-Control: no-store. GET /health/live проверяет процесс; /health/ready — соединение с PostgreSQL и точное совпадение Alembic heads. Readiness не доказывает доступность провайдеров.

Запись и восстановление неизвестного результата

1. Получить public catalog и availability.
2. Создать quote по идентификаторам услуг.
3. Создать hold на выбранную смену и время.
4. Подтвердить quote, hold и конкретную policy.
5. После потери ответа запросить /v1/me/command-status?operation=bookings.create&key=... либо повторить исходную команду с тем же ключом.

not_observed при чтении статуса не означает отказ: незавершённая транзакция ещё может зафиксироваться. Повторять разрешается тот же ключ. Новый ключ может создать другое намерение. Не копировать ключ от одного operationId к другому в качестве ссылки на операцию.

Внешние адаптеры

Telegram/Яндекс/MAX, YooKassa, vault, объектное хранилище, отправка уведомлений и purge worker не активированы. Их контракты, таблицы и узлы графа доступны в атласе. Фальшивых POST-success для этих действий нет. Настоящая авторизация клиента и внешний settlement требуют отдельной конфигурации адаптеров, проверки callback/webhook и разрешённых секретов. Сессия для интеграционных тестов создаётся только серверной fixture.