Перейти к основному содержимому

Общие Требования К Документам

Назначение​

Этот документ содержит общие cross-cutting требования, которые повторяются почти во всех архитектурных, контрактных, runtime и task-level документах. Остальные файлы должны ссылаться на него вместо дублирования одинаковых правил.

Обязательная Metadata​

Каждый рабочий документ, кроме коротких index-README, обязан явно содержать:

  • назначение;
  • owning team или owner;
  • статус документа;
  • область действия;
  • assumptions и ограничения;
  • зависимости;
  • связанные документы;
  • change context, если документ меняет существующее поведение.

Общие Требования К Данным И Моделям​

  • Все модели должны быть именованными и typed.
  • Для каждой named model должна быть таблица полей.
  • Порог «таблица vs список» для маппинга полей запроса/ответа задан в Правилах Документирования API: более 3–4 полей — таблица (поле | тип | обязательность | источник/маппинг | ограничения, опционально Примечания), 1–3 поля — список.
  • Любая коллекция должна жить внутри именованной container-model.
  • object, json, jsonb, payload, metadata, attributes, settings, parameters, context без полной схемы запрещены.
  • Для reference data используются explicit ids, а не неявные строковые коды как primary domain keys.

Общие Требования К Безопасности​

Каждый документ, описывающий runtime behavior, обязан явно фиксировать:

  • actor type;
  • permission или policy;
  • tenant/scope isolation rule;
  • требования к masking и data classification;
  • MFA/approval rule, если операция привилегированная;
  • trusted/untrusted input boundary.

Нельзя:

  • включать secrets, реальные токены и production credentials;
  • раскрывать raw PII без правила маскирования;
  • оставлять privileged operation без explicit access model.

Общие Требования К Наблюдаемости​

Каждый runtime-документ должен отвечать на вопросы:

  • какие logs пишет операция;
  • какие metrics обязательны;
  • какие traces и correlation ids должны присутствовать;
  • какой dashboard используется;
  • какой runbook связан с отказом.

Если раздел наблюдаемости неприменим, он ОПУСКАЕТСЯ целиком (не помечается «не применяется»).

Общие Требования К Совместимости​

Для внешних контрактов и versioned models обязательно:

  • compatibility rule;
  • additive vs breaking changes rule;
  • migration note;
  • unknown enum handling;
  • deprecation or sunset rule, если применимо.

Общие Требования К Ссылкам И Source Of Truth​

  • Документ должен ссылаться на upstream source of truth, если зависит от внешнего правила, ADR, контракта или шаблона.
  • Системный документ не вводит новый runtime contract без ссылки на детальную спецификацию.
  • Локальное повторение допустимо только если без него документ теряет самостоятельность.

Реестр «Один Дом На Концепт» (анти-дублирование)​

Каждый концепт документируется в ОДНОМ каноническом доме; остальные документы ссылаются и перечисляют только дельту/проекцию, а не переописывают таблицы полей.

КонцептДом (единственный)Кто ссылается (только дельта)
Контракт операции + CQRS + алгоритмapi-method-template (HTTP) / consumer-template (event)service-readme, feature-slice, use-case, frontend-feature-slice
Правило/паттерн CQRScommand-query-templateapi-method, consumer, background-job
Поля сущности/агрегатаentity-templatemodel, event-contract, clickhouse-fact, search-document, data-lineage, jsonb-document
Контракт Kafka-событияevent-contract-templateentity События, service-readme, use-case, consumer
Permission / policypolicy-permission-templateapi-method Актор, feature-slice, use-case, frontend-*
Переходы состояний / инвариантыentity-template (агрегат) / saga-template (кросс-сервис)domain-invariant, use-case

HTTP-endpoint и одна HTTP-операция описываются в ОДНОМ файле; то же — consumer и обрабатываемое им событие. Один концепт — один дом, остальные ссылаются на него.

Спеки в тексте не несут мета-фраз авторинга — «по [Правилам…]», «реестр «Один Дом на концепт»», «заполнен inline», шапки-boilerplate. Ссылка внутри спека ведёт на сам контракт (сущность, событие, соседняя операция), а не на правило документирования. Уровень изложения ссылок — по Уровню изложения ТЗ.

Общие Требования К Алгоритму​

Каждый документ операции (endpoint/consumer/job/use-case) содержит раздел ## Алгоритм, описывающий поведение на уровне бизнес-логики: какую сущность по каким условиям читать/проверять, какие бизнес- правила и переходы применять, что фиксировать и что происходит при успехе и при каждом отказе (с кодом ошибки). Уровень изложения — по Уровню изложения ТЗ, структура шагов — по Правилам Документирования Алгоритма. Без имён классов/хендлеров/ валидаторов, вызовов репозиториев, монады результата и транзакций SDK.

Общие Требования К Диаграммам​

Диаграммы опциональны: добавляй mermaid только там, где он проясняет нетривиальный поток; для тривиального CRUD диаграмму не рисуй. Если рисуешь — выбирай тип по задаче:

  • sequenceDiagram — операции (api-method/consumer), use-case, system-scenario, saga, провайдер-адаптер;
  • stateDiagram-v2 — entity (переходы), saga (state machine), domain-invariant;
  • erDiagram — entity (связи), service-readme, data-lineage;
  • flowchart — data-lineage, background-job, report-export, migration.

Участники sequenceDiagram — бизнес/доменные роли (актор, сервис, витрина, внешняя система), а не IDbRepository/IUnitOfWork/Handler/Outbox. Неприменимый раздел ОПУСКАЕТСЯ (не помечается «не применяется»).

Общие Требования К Стилю​

  • Пиши поведение конкретно: какие поля читаются, какие меняются, какие статусы разрешены, какие side effects происходят.
  • Не используй размытые формулировки без расшифровки.
  • Используй таблицы для перечислимых правил, статусов, approvals, constraints и controls.
  • Один файл отвечает на один основной вопрос и не подменяет соседние документы.

Обратные ссылки​

Автоссылки: где используется этот документ.