Cqrs Application Documentation Writing

Документирование прикладного слоя с CQRS

Собирать подтверждённые требования и превращать их в спецификации команд, запросов и составных сценариев. Описывать application композитором доменных операций: получение данных через порты, авторизацию, порядок действий, транзакционную границу, сохранение, публикацию и возвращаемый результат.

Архитектурная граница

Application может использовать публичные контракты domain и объявляет необходимые ему порты. Не использовать в application-документах модели presentation, транспортные envelope, HTTP-статусы, конкретные брокеры, SQL, реализации репозиториев и другие структуры внешних слоёв.

Presentation и infrastructure могут ссылаться на публичные application-команды, запросы, DTO, ошибки и порты без повторного определения. Application-документ не должен зависеть от документов внешних адаптеров. При необходимости внешнего ресурса описывать требуемый порт и его контракт, а не реализацию.

Статус сведений

Различать подтверждённое требование, принятое проектное решение, предложение и открытый вопрос. Не требовать отдельный раздел со статусами для полностью согласованного документа. Предложения и предположения помечать явно и не включать в нормативные таблицы как принятые решения.

Размещение и навигация

Размещать документы в слоте application/: общие DTO и порты — в contracts, канонические команды и запросы — в operations, составные сценарии — в scenarios. Не создавать параллельный корневой раздел pipelines, если принят слот application.

Считать команды, запросы, DTO и порты контрактами для реализации application- слоя. Составные сценарии предназначать для человека: ими объяснять путь к пользовательской или системной цели через несколько канонических операций. Не считать сценарий контрактом для реализации и не вводить ради него машинные статусы, входы или результаты, отсутствующие у участвующих операций.

Получение справочных данных документировать как query. Размещать такие операции по тем же правилам, что и остальные запросы: учитывать бизнес-возможность, инициатора, авторизацию и источник данных. reference_data использовать только для самостоятельной устойчивой группы справочных запросов.

Формировать только поддерево раздела «Прикладной слой». Индекс application/README.md предшествует контрактам, операциям и сценариям; каждый документ включается в навигацию один раз.

Рабочий процесс

Стабильные обозначения

Строить обозначение из отдельных смысловых сегментов. Для операций использовать <контекст>.application.operations.<commands|queries>.<user|system>.<ресурсы>.<действие>, например projects.application.operations.commands.user.projects.update. Для входного DTO использовать <контекст>.application.contracts.input.<ресурс>.<действие>, например projects.application.contracts.input.project.update. Не склеивать ресурс и действие (update_member_role) и не пропускать ресурс (input.update_project). Одинаковый контракт во всех документах имеет одно обозначение независимо от имени файла.

1. Определить цель, инициатора и вид документа: команда, запрос или составной сценарий.
2. Изучить согласованные domain-документы и структуру документации, не восстанавливая отсутствующие требования из кода.
3. Провести интервью по application-interview.md.
4. Отделить application-решения от доменных правил и транспортной политики.
5. Отделить подтверждённые требования и принятые решения от предложений и открытых вопросов.
6. Назначить стабильное обозначение переиспользуемому контракту, если на него ссылаются другие документы.
7. Зафиксировать минимальные входные и гарантированные выходные сведения, требуемые возможности портов, порядок действий, исходы и границы согласованности.
8. Создавать или дополнять один согласованный документ за шаг.
9. После ручного дополнения перечитать документ целиком и продолжить интервью с наиболее значимых противоречий или пробелов.
10. Проверить ссылки, владельцев контрактов, направление зависимостей и отсутствие дублирования domain-документов.
11. Оценить готовность документа к реализации и отметить, какие открытые вопросы блокируют всю реализацию, отдельную её часть или могут быть отложены.

Для команд, запросов и составных сценариев читать cqrs-pipelines.md.

Для входных границ, DTO, исходящих портов, авторизации, совместимости, внешних значений, транзакционных границ, публикации и ошибочных исходов читать application-boundaries.md.

Владение требованиями

• Domain владеет поведением, инвариантами, состояниями, доменными ошибками и событиями; ссылаться на его документы, не копируя их содержание.
• Application владеет DTO операций, авторизацией, оркестрацией, портами, транзакционными границами, сохранением, публикацией и публичными исходами операций.
• Presentation и transport владеют разбором внешнего ввода, сериализацией, транспортными ответами и политикой доставки.
• Infrastructure владеет реализацией портов и техническими механизмами.

Открытые вопросы

Каждый содержательный документ должен завершаться разделом ## Открытые вопросы. Закрытое решение переносить в основной раздел и удалять из списка. Если нерешённых вопросов нет, писать:

## Открытые вопросы

Открытых вопросов нет.

Ограничения

• Не сверять требования с кодом без отдельной явной просьбы.
• Не выдавать предположение или возможный технический механизм за принятое решение.
• Не включать предложения и предположения в нормативные таблицы как принятые решения.
• Не переносить доменную логику и классификацию доменных ошибок в application-документ; наблюдаемые результаты выражать application-исходами.
• Не разделять одну application-операцию только из-за разных транспортов.
• Не использовать составной сценарий как спецификацию реализации или отдельную входную границу application.
• Не выносить получение справочных данных из раздела запросов и не использовать transport-доступность public как критерий application-размещения.
• Не объединять разные контракты необязательным инициатором или флагом обхода прав.
• Не описывать конкретную реализацию порта.
• Не закреплять имена классов и методов, языковые типы, сигнатуры или структуру модулей.
• Писать документацию на языке пользователя или целевого репозитория.

Проверка

Перед завершением убедиться, что:

• операция имеет однозначные цель, инициатора, вход и результат;
• зафиксированы только минимально необходимые входные и гарантированные выходные сведения;
• DTO и порты принадлежат application, а не внешнему адаптеру;
• входная операция отделена от используемых ею исходящих портов;
• исходящие возможности разделены по смысловой ответственности без навязывания структуры интерфейсов;
• для каждого входа и результата порта однозначно указана смысловая форма: существующий domain VO, неизменяемый application DTO или обоснованное техническое значение;
• закрытое объединение существующих DTO описано без инфраструктурного перечисления типов, а постоянный порядок и переходы состояния принадлежат соответствующему порту;
• при раздельных портах состояния, истории и outbox каждая изменяющая команда явно вызывает все требуемые возможности в одной согласованной транзакционной границе;
• определены инициатор, область и порядок application-авторизации;
• для переиспользуемых контрактов указаны потребители и смысловые гарантии;
• общий ожидаемый результат порта и операции принадлежит application DTO, а не внутреннему контракту адаптера;
• все возможности портов представлены таблицами с единым набором обязательных колонок;
• команды, пользовательские запросы, справочные запросы, системные команды и сценарии используют закреплённые структуры и порядок разделов;
• раздел ссылок на доменные и application-контракты в операциях называется Используемые контракты;
• стабильные обозначения содержат отдельные сегменты вида операции, инициатора, ресурса и действия без склеивания ресурса с действием;
• выходной раздел операции ссылается на DTO и доменный источник, но не дублирует конкретные значения доменного состояния;
• переиспользуемые контракты имеют стабильные обозначения;
• неподтверждённые сведения имеют однозначный статус;
• определены влияющие на результат внешние значения и их поведение при повторе;
• определены связь публикации с сохранением и её влияние на завершение операции;
• успешные и ошибочные исходы сведены в итоговую таблицу;
• каждый наблюдаемый доменный отказ преобразован в публичный application-исход;
• реализация не требует придумывать отсутствующие application-требования;
• для каждого открытого вопроса указано его влияние на готовность реализации;
• application-документ использует domain-контракты только в направлении зависимости application → domain;
• документы не содержат моделей или политик presentation и infrastructure;
• доменное поведение заменено ссылками на документы владельцев;
• относительные ссылки разрешаются;
• документы расположены внутри application/, а навигационный фрагмент не меняет порядок глобальных разделов;
• документ завершается обязательным разделом Открытые вопросы, включая Открытых вопросов нет. при отсутствии вопросов.