Принципы и инварианты

Зачем нужно

Документ фиксирует архитектурные и продуктовые правила, которые обязаны соблюдать все домены, platform-слой и AI-агенты. Любое нарушение этих правил — повод исправить домен, а не правило.

Язык документации

• Документация пишется на русском языке.
• Английский используется только для технических терминов: имена API, протоколов, сущностей, полей, событий, кодов ошибок, библиотек, фреймворков.
• Frontmatter использует английские ключи (title, status, version) и значения на русском там, где это естественно.

Канонические инварианты

Идентификация и доступ

1. Один identity-пользователь — один аккаунт.
2. Пользователь не равен роли, родителю, ребёнку, преподавателю, клиенту или участнику олимпиады.
3. Действие в контексте ребёнка или организации моделируется через actor_context, а не подменой user_id.
4. Семья и организация — разные модели доступа и не смешиваются.
5. RBAC проверяется на сервере; фронтенд скрывает элементы, но не отвечает за безопасность.
6. Пароль обязателен у каждого пользователя, даже если включён OTP/OAuth.
7. Глобальной роли teacher нет: преподавательский доступ определяется назначением, членством, grants и product permissions.
8. educator_profile — анкета, контакты, предметы, классы и trust status; он не является источником прав.

Reference-слой

9. Reference-данные (subject, level, format, grade_range) определяются platform-слоем и не переопределяются в доменах.
10. Доменная сущность не дублирует reference-данные локально; она ссылается на ключ.

Учебная модель

11. Тема дорожной карты (roadmap_topic) не равна уроку (lesson), занятию (session) и задаче (problem).
12. Урок не равен занятию.
13. Прогресс по теме (topic_progress), прогресс по уроку (lesson_progress) и прогресс по продукту (product_progress) хранятся раздельно.
14. Посещаемость (attendance) не означает завершение темы (topic_completion).
15. Геймификация (xp, badge, streak) не подменяет академическое завершение темы.
16. Связь занятия с темой (session_topic_link) и связь занятия с уроком (session_lesson_link) — явные сущности, а не неявные совпадения.
17. Mini-group track — частный механизм мини-групп, а не универсальный topic pathway.
18. Learning Workspace — общий рабочий слой преподавателя, а не identity, организация, LMS-группа живого курса, олимпиадная группа или семья.
19. Обычные рабочие ученики преподавателя моделируются через learning_group_participant; organization_student используется только для официального/подтверждённого организационного контура.

Коммерция

20. Продукт (product) не равен программе обучения, группе, потоку и реализации во времени.
21. Реализация продукта (product_run) и группа (group) — разные сущности.
22. Покупка (order), участие (enrollment) и право доступа (entitlement) — три разные сущности.
23. CRM владеет коммерческой стороной занятия, LMS владеет учебной стороной. Граница проходит по entitlement_consumption.

Витрина

24. Storefront — read-model. Витрина не владеет ни одной канонической сущностью кроме своих публичных страниц, блоков, форм и SEO.
25. Публичная и авторизованная проекции дорожной карты — разные представления одной модели LMS, не отдельные источники истины.

Банк задач

26. Задача (problem) не равна теме (roadmap_topic).
27. Использование задачи (problem_usage) описывается явно, а не выводится по совпадению уроков и файлов.
28. Low-level попытка проверки задачи (problem_attempt) и проверка ответа (answer_check) — разные сущности и не заменяют LMS/competition attempts.

Олимпиады

29. Competitions используют identity, task-bank, crm и lms как источники, но не дублируют их сущности.
30. Участник олимпиады может существовать без учётной записи в identity (внешний ученик), но после claim не должен создавать второй активный participant на тот же identity_user_id в одном сезоне. Компромисс закреплён ADR-031.
31. Родитель регистрирует ребёнка и наблюдает в родительском режиме, но не становится ребёнком; прохождение олимпиады ребёнком идёт в детском режиме.

Платформа

32. Каждое API-наружу домена соответствует api-conventions.
33. Каждое cross-domain событие следует контракту events-bus.
34. Каждый домен использует общую UI-систему из ui-system, а не собственный набор токенов.
35. Аудит, логи, метрики и трассировка ведутся по observability.

Документация

36. У каждой канонической сущности есть владелец (домен) в ownership.md.
37. Документ в активном target/ содержит самодостаточное целевое решение и не ссылается на внешние рабочие материалы как на источник истины.
38. Если термин не зафиксирован в glossary.md, он не используется как канонический в коде, схемах данных и API.
39. Входные материалы нормализуются в канонические документы target/ до использования в разработке.
40. AI-агенты не вводят новых сущностей, статусов и терминов без проверки по glossary.md, ownership.md и доменным спецификациям.

Запреты

• Не делать read-model владельцем сущности.
• Не считать копию данных в другом сервисе источником истины.
• Не назначать двух владельцев одной сущности.
• Не переопределять reference-данные в доменах.
• Не размещать платформенные правила (API-формат, события, RBAC) внутри одного домена.