How-to: изменить контракт (событие)¶

Контракт — источник правды и ворота (CLAUDE.md, концепт раздел 7). Любое появление/изменение/удаление события — PR в contracts/.

Добавить новое событие¶

Схема — contracts/schemas/<сущность>.<событие>.v1.json (JSON Schema draft 2020-12).
AsyncAPI — в contracts/asyncapi.yaml:
канал с address: <сущность>.<событие>.v1 (именование);
сообщение с payload.$ref на схему;
операцию send/receive (кто публикует/потребляет).
Каталог — пересобрать и закоммитить:
```
python tools/gen_catalog.py   # -> docs/catalog.md
```
PR → CI (contracts.yml) валидирует схемы, именование, ссылки и свежесть каталога.

Совместимое изменение¶

Новое опциональное поле, новое событие, новый потребитель — катятся свободно (аддитивно, безопасно по построению). Обнови схему + каталог, PR.

Ломающее изменение → новая версия (никогда на месте)¶

Удаление/переименование поля, смена типа/семантики: 1. Заведи новый subject ….v2 (новая схема, канал, операции) — рядом со старым .v1. 2. Параллельный период: продюсер публикует обе версии (или v2 + мост), потребители мигрируют в своём темпе. 3. Когда трафик на .v1 обнулился (видно по каталогу/трейсингу) — выведи .v1 (PR: убрать канал/схему), очисти осиротевшие консьюмеры.

Это expand/contract: новое живёт рядом со старым, старое выводится последним (#4).

Проверка локально перед PR¶

python tools/validate_contracts.py   # схемы, именование, ссылки
python tools/gen_catalog.py          # каталог в актуальном виде