Passport — индекс канонического контракта PM¶

Раздел passport/ — это канонический технический контракт Payment Manager: DTO, channel-коды, operationType, события, коды ошибок и HMAC-сервисы. Любое изменение публичного контракта PM начинается здесь.

Назначение раздела¶

До реорганизации канонический контракт PM хранился в монолитном файле PASSPORT.md в корне проекта (~62 KB). Он стал плохо обозримым: при изменении одного channel-кода приходилось искать по всему файлу. Поэтому контракт разнесён на 6 тематических файлов (01-06), каждый из которых отвечает за один аспект контракта и обновляется независимо.

Корневой файл PASSPORT.md остаётся как тонкий index-манифест (~50 строк): даёт верхнеуровневую карту и ссылается на этот раздел. Все детали — здесь.

Структура раздела¶

Файл	Что внутри
`./01-dto-contracts.md`	Все Zod-схемы request/response endpoint'ов PM (`/intents`, `/intents/quote`, `/intents/:id/confirm`, `/intents/:id/cancel`, `/policies/*` и др.).
`./02-channels.md`	Реестр channel-кодов: `INTERNAL_P2P`, `IPPS_TRANSFER`, `SERVICE_TRANSFER`, `ADMIN`, `MERCHANT_INVOICE`.
`./03-operation-types.md`	Реестр operationType (11 шт.) — что значит каждый, какой channel применим, какие fields обязательны.
`./04-event-types.md`	Outbox actions, Redis pub/sub каналы (`intent.{id}`, `user.{id}.intents`) и заготовка под Redis Streams (Phase 2B).
`./05-error-codes.md`	Реестр кодов ошибок PM — что возвращает endpoint, какой HTTP-статус, в каких случаях.
`./06-service-keys.md`	Реестр HMAC-сервисов (`auth-center`, `nginx-gateway`, `admin-panel`, ...) и их permissions (какие endpoints/operationType разрешены).

Правила обновления¶

Контракт PM — публичный, его изменения затрагивают все клиенты (Auth Center, Admin Panel, nginx-gateway). Поэтому при любом изменении контракта обязательно обновлять связанные файлы:

Новый channel → обновить 02-channels.md, а также 06-service-keys.md (если хотя бы у одного service-key добавляется доступ к этому channel) и 04-event-types.md (если появляется новое событие, специфичное для channel).
Новый operationType → обновить 03-operation-types.md и добавить пошаговый рецепт в ../../cookbook/add-operation-type.md.
Новый service-key → обновить 06-service-keys.md и ../../cookbook/add-service-key.md.
Новый код ошибки → обновить 05-error-codes.md (код, HTTP-статус, причина, поле в response).
Изменение Zod-схемы → обновить 01-dto-contracts.md, а также соответствующий endpoint-документ в ../../api/, если изменился публичный API.

Принцип: passport — источник правды. Если код расходится с passport, ошибка либо в коде, либо в passport — но не у клиента.

История¶

Git-история монолитного PASSPORT.md сохранена:

git log --all -- PASSPORT.md

Используй её, чтобы поднять контекст изменений контракта до реорганизации.