Nemagu Документирование доменной модели
Собирать подтверждённые требования и превращать их в спецификации domain-слоя. Описывать домен владельцем бизнес-поведения, инвариантов, состояний, доменных отказов и событий, не перенося в него ответственность внешних слоёв.
Архитектурная граница
Domain не зависит от application, presentation и infrastructure. Не использовать в доменных документах команды, запросы, DTO, модели транспорта, схемы хранения, фреймворки и реализации адаптеров как части доменного контракта.
Внешние документы могут ссылаться на публичные доменные контракты. Domain-документ не должен ссылаться на структуры внешнего слоя. Если доменному правилу нужны сведения извне, описывать их бизнес-смысл, владельца и минимальный доменный контракт передачи или получения, не предписывая внешний механизм.
Статус сведений
Различать подтверждённое требование, принятое проектное решение, предложение и открытый вопрос. Не требовать отдельный раздел со статусами для полностью согласованного документа. Предложения и предположения помечать явно и не включать в нормативные таблицы как принятые решения.
Размещение и навигация
Размещать документы в слоте domain/ принятой структуры. Внутренние каталоги
aggregates, projections, value-objects, services и events создавать
только при наличии соответствующих документов и пользы для навигации.
Формировать только поддерево раздела «Доменная модель»: индекс domain/README.md
предшествует дочерним группам, каждый документ включается один раз. Не создавать
параллельные корневые каталоги contexts или domain-model, если слот domain
уже принят.
Внутри доменного поддерева располагать общие объекты-значения, проекции, агрегаты, затем доменные события, если структура репозитория не задаёт иной порядок явно.
Рабочий процесс
Стабильные обозначения
Строить обозначение из отдельных смысловых сегментов по общей схеме
<контекст>.domain.<категория>.<объект>.<уточнение>. Не склеивать объект и
уточнение в одном сегменте и не пропускать объект. Использовать, например,
projects.domain.aggregates.project и projects.domain.events.project.created,
а не projects.domain.events.project_created. Одинаковый контракт во всех
документах имеет одно обозначение независимо от имени файла.
- Определить документируемый контекст и объект, его владельца и границу.
- Изучить принятую структуру документации и связанные документы, не восстанавливая отсутствующие требования из кода.
- Провести предметное интервью по domain-interview.md.
- Отделить подтверждённые требования и принятые решения от предложений и открытых вопросов.
- Назначить стабильное обозначение контракту, если на него ссылаются другие документы.
- Создавать или дополнять один согласованный документ за шаг.
- После ручного дополнения перечитать документ целиком и продолжить интервью с наиболее значимых противоречий или пробелов.
- Проверить владельца поведения, инварианты, типы, события, ссылки и направление зависимостей.
- Оценить готовность документа к реализации и влияние каждого открытого вопроса.
Выбор справочника
- Для агрегатов, сущностей, value objects, доменных сервисов и проекций читать domain-objects.md.
- Для доменных событий читать domain-events.md.
Владение требованиями
- Агрегат владеет поведением и инвариантами внутри своей границы.
- Доменный сервис владеет правилом, которое естественно не принадлежит одному агрегату.
- Агрегат не изменяет другой агрегат и не владеет порядком их загрузки или сохранения.
- Проекция владеет локальным представлением, но не исходными данными другого контекста.
- Доменное событие принадлежит породившему его контексту и доменному источнику. Оно не становится внешним интеграционным контрактом автоматически.
- Application владеет оркестрацией, авторизацией, транзакционной границей, сохранением и публикацией; не описывать их доменным поведением.
- Domain может владеть бизнес-правилом о полномочии участника модели, если решение следует из доменного состояния и должно соблюдаться независимо от сценария вызова. Не подменять таким правилом application-авторизацию инициатора.
Готовность к реализации
Считать доменный документ готовым, когда разработчик может выбрать техническую реализацию, не придумывая границу модели, бизнес-семантику, инварианты, поведение, отказы или события. Допускать частичную готовность, если граница готовой части указана явно.
Открытые вопросы
Каждый содержательный документ должен завершаться разделом
## Открытые вопросы. Закрытое решение переносить в основной раздел и удалять из
списка. Для каждого вопроса указывать затронутую часть и влияние: блокирует весь
документ, блокирует отдельную часть или может быть отложен. Если нерешённых
вопросов нет, писать:
## Открытые вопросы
Открытых вопросов нет.
Ограничения
- Не сверять требования с кодом без отдельной явной просьбы.
- Не выдавать предположения и технические предпочтения за бизнес-решения.
- Не включать предложения и предположения в нормативные таблицы как принятые решения.
- Не навязывать Python-классы, SQL, брокер, transport envelope или структуру модулей.
- Не дублировать application-сценарии в доменном поведении.
- Не создавать общий объект между контекстами только из-за совпадения структуры.
- Писать документацию на языке пользователя или целевого репозитория.
Проверка
Перед завершением убедиться, что:
- объект имеет одного владельца и однозначную границу;
- для агрегатов и сущностей определена идентичность, для объектов-значений — равенство по значению;
- создание нового объекта отделено от восстановления сохранённого состояния;
- создание описано ровно один раз в разделе поведения, а общее для агрегатов восстановление сохранённого состояния не продублировано по файлам;
- общие объекты-значения используются несколькими доменными объектами, локальные находятся в явном разделе использующего объекта и не содержат его инварианты;
- состояния, статусы, роли и другие доменные перечисления классифицированы как объекты-значения, а разделы жизненного цикла не создают для них отдельные типы;
- переходы состояний оформлены единообразно и содержат отдельные идемпотентные исходы, когда они предусмотрены;
- все заявленные операции поведения и порождаемые события перечислены, а у событий агрегата есть краткая таблица либо явно зафиксировано их отсутствие;
- инварианты и бизнес-полномочия отделены от application-авторизации и предусловий сценария;
- каждая операция поведения имеет минимальный однозначный доменный контракт;
- семантика повторного вызова определена для каждой операции, где повтор возможен;
- каждый доменный отказ связан с правилом и имеет определённые последствия;
- межагрегатные правила не нарушают границы агрегатов и имеют определённые требования к согласованности;
- доменные документы не используют структуры внешних слоёв;
- доменные события сформулированы как свершившиеся факты, связаны с источником и отделены от интеграционных контрактов;
- переиспользуемые доменные контракты имеют стабильные обозначения;
- неподтверждённые сведения имеют однозначный статус;
- реализация не требует придумывать отсутствующие доменные требования;
- для каждого открытого вопроса определено влияние на готовность;
- относительные ссылки разрешаются;
- документы расположены внутри
domain/, а навигационный фрагмент не меняет порядок глобальных разделов; - документ завершается обязательным разделом
Открытые вопросы, включаяОткрытых вопросов нет.при отсутствии вопросов.