Целевая документация экосистемы

Документация описывает целевое состояние экосистемы Systematika и устроена так, чтобы по ней можно было разработать продукт с нуля без вопросов и противоречий.

Структура

Папка	Назначение
ecosystem/	Продуктовая рамка: что такое экосистема, инварианты, словарь, карта 7 доменов, владение, сквозные сценарии
platform/	Техническая рамка: стек, топология, API, auth, RBAC, события, observability, UI-система, reference-данные, порядок разработки
decisions/	Архитектурные решения (ADR)
domains/	Спецификации 7 доменов: identity, storefront, crm, lms, task-bank, competitions, management
integrations/	Cross-domain контракты, по файлу на каждую интеграционную линию
migration/	Переход от текущего состояния к целевому
templates/	Обязательные шаблоны новых документов

Путь чтения для разработчика с нуля

1. ecosystem/overview.md, ecosystem/principles.md, ecosystem/glossary.md, ecosystem/domain-map.md, ecosystem/ownership.md.
2. platform/overview.md и далее весь platform/.
3. decisions/README.md — список действующих ADR.
4. platform/development-order.md — какой домен разрабатывать первым.
5. Целевой домен в domains/<name>/: overview.md → scope.md → data-model.md → database-schema.md → state-machines.md → api-map.md → api-contracts.md → permissions-matrix.md → events.md → screen-spec.md → user-flows.md → security.md → integrations.md → test-plan.md → acceptance.md → подспеки в features/.
6. Сводные integrations/<source>--<target>.md для всех точек обмена.
7. migration/ — только если перенос существующих данных нужен.

Как работать с документацией

Документация живёт в Docusaurus-приложении apps/docs. Все страницы находятся в apps/docs/docs/, а целевая документация — в apps/docs/docs/target/.

Локальный запуск

Перед большой правкой лучше запустить сайт локально и смотреть результат в браузере:

npm install
npm run docs

Открыть:

http://127.0.0.1:3103/target

Для финальной проверки:

npm run docs:build

Если менялись ссылки, sidebar, frontmatter или много файлов сразу, сборка обязательна: Docusaurus быстро показывает битые ссылки, неверные doc id и ошибки разметки.

Перед правкой

1. Определить, к какому слою относится изменение:
   • ecosystem/ — понятия, инварианты, карта доменов, ownership;
   • platform/ — общий технический стек, API-конвенции, auth, RBAC, события, CI/CD, observability, UI;
   • domains/<name>/ — логика конкретного домена;
   • integrations/ — обмен между доменами;
   • migration/ — перенос из текущего состояния в целевое;
   • decisions/adr/ — архитектурное решение, которое нужно зафиксировать отдельно.
2. Найти источник истины. Если правка касается сущности, владельца или статуса, сначала проверить ecosystem/ownership.md, ecosystem/domain-map.md, доменный data-model.md и database-schema.md.
3. Проверить связанные документы. Изменение в одном файле редко бывает изолированным: API, события, права, state machine, сценарии, тест-план и acceptance должны остаться согласованными.
4. Понять статус решения. Если команда ещё не договорилась, документировать как draft или добавить отдельный ADR с явным статусом.

Как вносить небольшую правку

Небольшая правка — это уточнение текста, исправление ошибки, добавление недостающего правила без изменения архитектурной модели.

1. Открыть нужный .md файл.
2. Исправить текст рядом с местом, где уже описана эта тема.
3. Не создавать новый раздел, если информация логически продолжает существующий.
4. Если добавлена новая сущность, роль, permission, event, endpoint или статус, проверить соседние канонические файлы домена.
5. Обновить updated во frontmatter только у файлов, где смысл действительно изменился.
6. Запустить npm run docs:build, если правка затронула ссылки, заголовки, sidebar или несколько документов.

Пример: если в domains/lms/api-contracts.md добавлен новый endpoint, нужно проверить минимум api-map.md, permissions-matrix.md, events.md, test-plan.md и acceptance.md.

Как добавлять новый документ

1. Выбрать правильную папку. Документ должен лежать рядом с ближайшим источником истины, а не в общей папке "на всякий случай".
2. Взять подходящий шаблон из templates/:
   • overview.md — обзор области;
   • specification.md — детальная функциональная спецификация;
   • api-contracts.md — API-контракты;
   • events.md — события;
   • data-model.md и database-schema.md — модель данных и DDL;
   • permissions-matrix.md — роли и права;
   • state-machines.md — статусы и переходы;
   • test-plan.md и acceptance.md — проверка и критерии готовности;
   • adr.md — архитектурное решение.
3. Создать .md файл с frontmatter:

---
title: Название документа
sidebar_label: Короткое название
sidebar_position: 10
status: draft
version: v3.0
updated: 2026-05-01
owners:
  - product
  - architecture
canonical: false
---

4. Поставить canonical: true только если документ является источником истины, а не заметкой, черновиком или вспомогательным материалом.
5. Добавить ссылку на новый документ из ближайшего overview.md, README.md или карты документов.
6. Если раздел управляется через _category_.json, проверить, что label, position и generated index не конфликтуют с новым файлом.
7. Запустить npm run docs:build.

Как добавлять новую доменную функцию

Для новой функции внутри домена не хватает одного feature-файла. Нужно провести изменение по всей цепочке:

1. scope.md — входит ли функция в границы домена и что не входит.
2. data-model.md — какие сущности, атрибуты и связи появляются.
3. database-schema.md — таблицы, enum-ы, индексы, ограничения, audit-поля.
4. state-machines.md — статусы, переходы, запреты и side effects.
5. api-map.md и api-contracts.md — endpoints, команды, queries, ошибки.
6. permissions-matrix.md — кто может читать, создавать, менять, удалять и администрировать.
7. events.md — какие события публикуются и кто их потребляет.
8. screen-spec.md и user-flows.md — как пользователь проходит сценарий.
9. security.md — риски, ограничения доступа, аудит, персональные данные.
10. integrations.md домена и сводный файл в integrations/, если функция общается с другим доменом.
11. test-plan.md и acceptance.md — как проверить, что функция готова.
12. features/<feature>.md — детальная спецификация, если логика крупнее нескольких правил.

Если на одном из шагов обнаруживается архитектурное решение, которое нельзя вывести из уже принятых правил, нужно добавить ADR.

Как менять архитектурное решение

Архитектурное решение нельзя менять только правкой текста в доменном файле.

1. Найти действующий ADR в decisions/adr/.
2. Если решение меняется по сути, создать новый ADR по шаблону templates/adr.md.
3. В новом ADR явно указать, что он заменяет, уточняет или отменяет прежний ADR.
4. Обновить все документы, где старое решение было источником правил.
5. В decisions/README.md проверить список действующих ADR.

ADR нужен, если меняется ownership, source of truth, граница домена, интеграционная стратегия, модель авторизации, event bus, способ миграции или публичный контракт.

Как добавлять интеграцию между доменами

1. Описать интеграцию в доменном integrations.md у владельца source of truth.
2. Создать или обновить сводный файл integrations/<source>--<target>.md.
3. Зафиксировать направление данных: кто владеет фактом, кто читает проекцию, кто имеет право отправлять command.
4. Описать API, события, retry/idempotency, ошибки, аудит и privacy-ограничения.
5. Обновить events.md, api-contracts.md, permissions-matrix.md, security.md, test-plan.md и acceptance.md затронутых доменов.

Нельзя описывать интеграцию как "домены синхронизируются" без указания владельца факта, формата обмена и поведения при ошибке.

Как удалять или переименовывать документы

1. Проверить входящие ссылки через поиск по названию файла и заголовку.
2. Обновить ссылки в overview.md, README.md, sidebars.js, _category_.json и связанных документах.
3. Если документ был canonical, перенести его правила в новый canonical-документ до удаления.
4. Если меняется URL важной страницы, добавить redirect в Docusaurus-конфиг или сохранить страницу-заглушку со ссылкой на новое место.
5. Запустить npm run docs:build.

Стиль текста

• Писать на русском. Английский использовать для кода, API, entity names, event names, полей, библиотек и общепринятых технических терминов.
• Начинать раздел с назначения и границы: зачем это нужно, кто владеет, что входит и что не входит.
• Писать правила так, чтобы по ним можно было реализовать систему: кто делает действие, при каком условии, какой результат, какой запрет.
• Не оставлять фразы без последствий для разработки: "должно быть удобно", "система поддерживает", "данные синхронизируются" нужно раскрывать конкретными сценариями, контрактами или критериями.
• Не дублировать большие фрагменты между файлами. В одном месте хранится источник истины, в остальных — ссылка и краткое применение.
• Для списков сущностей, ролей, прав, статусов, событий и endpoint-ов использовать таблицы.
• Для последовательностей использовать нумерованные шаги.
• Для спорных мест писать явно: Решение, Причина, Последствия, Нерешённые вопросы.

Frontmatter и статусы

Каждый целевой документ должен иметь frontmatter.

Поле	Как использовать
title	Полный русский заголовок страницы
sidebar_label	Короткое название для меню
sidebar_position	Порядок внутри раздела
status	draft, active или deprecated; для ADR используется отдельный lifecycle proposed, accepted, superseded, deprecated
version	Версия конкретного документа или спецификации; версия всей целевой документации задаётся этим index-документом
updated	Дата смысловой правки в формате YYYY-MM-DD
owners	Команды или роли, отвечающие за содержание
canonical	true, если документ является источником истины

draft означает, что по документу нельзя начинать разработку без подтверждения. active означает, что документ является рабочим основанием. deprecated означает, что документ оставлен для истории и должен ссылаться на актуальную замену. ADR с accepted является обязательным архитектурным решением; superseded ADR остаётся историческим источником и должен ссылаться на замену.

Чеклист перед завершением правки

• Изменение находится в правильном слое документации.
• У правки есть один понятный source of truth.
• Ссылки относительные и ведут на существующие файлы.
• Нет противоречий между overview, scope, data-model, database-schema, API, permissions, events, security, test-plan и acceptance.
• Если поменялась граница домена или ownership, добавлен или обновлён ADR.
• Если появился новый статус, event, permission, endpoint или enum, он отражён во всех связанных файлах.
• updated обновлён только там, где изменился смысл.
• npm run docs:build проходит без ошибок.

7 доменов экосистемы

• identity/ — аккаунты, OAuth, роли, семьи, организации, безопасность.
• storefront/ — публичная витрина и read-model.
• crm/ — клиенты, сделки, биллинг, entitlements, выплаты преподавателям.
• lms/ — учебный кабинет, курсы, уроки, прогресс, занятия, дорожная карта, геймификация.
• task-bank/ — задачи, таксономия, попытки, evidence.
• competitions/ — олимпиады и внешний преподавательский контур.
• management/ — аналитика, dashboards, цели, рекомендации, диагностика, планирование.

Стандарт качества

Документация считается готовой, когда:

• каждый домен покрыт каноническим набором из 15 файлов;
• все архитектурные и продуктовые решения находятся в активной целевой документации;
• глоссарий, ownership и domain-map согласованы между собой и с domains/;
• platform-слой описывает один общий стек, конвенции и инфраструктуру;
• каждая cross-domain интеграция имеет файл в integrations/;
• ADR покрывают неочевидные решения и не дублируются.