Готовность экосистемы

Зачем нужно

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

Готовность документации

• index.md объявляет 7 доменов и платформенные слои.
• ecosystem/ содержит overview, principles, glossary, domain-map, ownership, integrations, user-journeys, acceptance.
• platform/ описывает стек, топологию, API-конвенции, auth, RBAC, события, observability, UI-систему, reference-данные, security baseline, data baseline, frontend baseline, CI/CD, порядок разработки.
• decisions/ содержит действующие ADR без пробелов.
• У каждого из 7 доменов есть полный канонический набор из 15 файлов.
• У каждой канонической сущности один владелец в ownership.md.
• Каждый термин в glossary.md имеет владельца.
• В integrations/ файл на каждую cross-domain линию из domain-map.md.
• Ни один документ в target/ не ссылается на archive/ как на источник истины.
• Все ссылки внутри target/ валидны (Docusaurus собирается с onBrokenLinks: throw).

Готовность 7 доменов

Для каждого домена:

• overview.md — что входит, что не входит, владение, главные правила, карта документов, порядок разработки.
• scope.md — акторы, границы, контексты действия.
• data-model.md — канонические сущности и связи.
• database-schema.md — PostgreSQL DDL.
• state-machines.md — все статусные модели.
• api-map.md — каталог endpoints.
• api-contracts.md — DTO, validation, response schemas, ошибки.
• permissions-matrix.md — action → permission → scope → audit.
• events.md — входящие команды и исходящие события.
• screen-spec.md — экраны, состояния, поля.
• user-flows.md — внутридоменные сценарии.
• security.md — PII, аудит, rate limits.
• integrations.md — ссылки на integrations/<source>--<target>.md.
• test-plan.md — unit/integration/e2e/security.
• acceptance.md — критерии готовности домена.
• features/ — глубокие подспеки по специфике.

Готовность platform-слоя

• стек объявлен (язык, фреймворк, БД, очередь, кеш, фронтенд);
• API-envelope, ошибки, пагинация, идемпотентность, версионирование;
• контракт authorization-сервера и распространения токенов;
• глобальная модель permissions и проверки;
• контракт шины событий (naming, payload, retention, идемпотентность);
• reference-данные (subject/level/format/grade_range);
• UI Kit и дизайн-токены;
• observability: logs, audit, metrics, tracing;
• security baseline: secrets, headers, cookies, rate limits;
• data baseline: PostgreSQL conventions, миграции;
• frontend baseline: маршруты, защищённые маршруты, API-клиент;
• CI/CD: сборка, тесты, релизы, окружения;
• порядок разработки 7 доменов.

Готовность интеграций

• для каждой пары <source, target> в матрице есть файл в integrations/;
• каждый файл фиксирует источник, потребителя, события/сущности, идемпотентность, ошибки, scopes, retention;
• integrations/README.md содержит сводную матрицу.

Готовность миграции

• описано текущее состояние;
• описано целевое состояние;
• описаны фазы и порядок;
• для каждого домена есть migration/data-mapping/<domain>.md;
• описана стратегия cutover, dual-write, backfill, rollback;
• риски явно перечислены.

Готовность к разработке с нуля

Документация считается достаточной для ground-up разработки, когда выполнены пункты выше и новый разработчик, прочитавший документацию по пути из index.md, может:

• собрать локально стек платформы;
• развернуть пустой identity-сервис, удовлетворяющий API-контрактам;
• создать тестовую витрину, читающую публичные данные;
• провести через систему сквозной путь покупки и доступа к курсу;
• описать новую сущность и однозначно отнести её к одному из 7 доменов или platform-слою.