Принципы межсервисных интеграций

Зачем нужно

Документ задаёт правила, по которым домены обмениваются данными. Конкретные контракты по каждой интеграционной линии описаны в папке ../integrations/.

Главные правила

1. У каждой интеграции есть один источник истины и один или несколько потребителей.
2. Потребитель не становится владельцем переданной сущности.
3. Online-чтение чужих данных делается через API-домена-владельца, а не через прямой доступ к его БД.
4. Cross-domain состояние распространяется через события на общей шине (events-bus).
5. Каждое сообщение шины идемпотентно по message_id.
6. Каждая интеграция описана отдельным документом в ../integrations/<source>--<target>.md.

Виды интеграций

Вид	Когда используется	Пример
online read	потребителю нужен свежий ответ во время запроса	identity userinfo по токену
event-driven	потребитель хранит свою проекцию	crm подписан на lms.entitlement.consumed
sync snapshot	периодическая выгрузка	management читает агрегаты
domain command	потребитель просит источник изменить состояние	crm вызывает lms для активации enrollment

Что входит в контракт интеграции

Каждый файл integrations/<source>--<target>.md обязан содержать:

• источник истины и потребитель;
• сущности и события;
• вид интеграции;
• формат payload (JSON Schema или DTO);
• правила идемпотентности и retry;
• ошибки и компенсации;
• права и scopes;
• retention событий и логов;
• связи с ADR.

Целевые интеграционные линии

Полный список — в ../integrations/README.md. Главные линии:

• identity ↔ все домены: пользователь, роли, actor context, OAuth tokens;
• storefront → crm: лиды;
• crm ↔ lms: entitlement активируется в crm, потребляется в lms, факт потребления возвращается в crm;
• crm → competitions: entitlement на участие;
• lms → storefront: публичная проекция дорожной карты;
• lms → management: учебные факты, прогресс, evidence, геймификация;
• task-bank → lms: задачи в уроках, домашках, диагностике;
• task-bank → competitions: content/source refs для tour activity binding;
• competitions → management: результаты, участие;
• crm → management: финансовые и операционные агрегаты;
• storefront → management: метрики витрины;
• management → lms (обратная связь): рекомендации, цели, диагностические задания;
• management → crm (обратная связь): план команд, операционные задачи.

Правила фиксации новой интеграции

1. Проверить, нет ли уже файла на эту линию в ../integrations/.
2. Создать <source>--<target>.md по templates/integration.md.
3. Добавить упоминание в ../integrations/README.md.
4. Если меняется владение — оформить ADR.
5. Обновить events.md источника и потребителя соответствующей ссылкой.

Что запрещено

• Прямой доступ к БД другого домена.
• Передача raw PII в события без явного указания в контракте.
• Скрытый дублирующий sync без описания в integrations/.
• Использование read-model в качестве owner.