Nemagu Документирование presentation-слоя
Координировать документацию внешних точек входа, сохраняя границы гексагональной архитектуры. Не дублировать подробные правила специализированных транспортов.
Архитектурная граница
Presentation зависит от публичных application-контрактов и не обращается к domain напрямую. Фиксировать направление зависимости:
внешний контракт → presentation → application → domain
Presentation владеет внешними моделями, транспортной валидацией, получением доверенного контекста, преобразованиями и внешними исходами. Application владеет сценарием, авторизацией и публичными application-исходами. Domain владеет бизнес-правилами и доменными отказами.
Не публиковать application DTO как внешнюю модель и не преобразовывать доменный отказ непосредственно во внешний исход.
К presentation также относятся внутренние driving entry points, которые сами инициируют application-операции по времени или внутреннему условию. Они не имеют внешней входной модели, но принадлежат тому же направлению зависимости.
Размещение и навигация
Размещать presentation-документы в едином слоте presentation/:
- HTTP API —
presentation/http/; - входящие сообщения —
presentation/messages/; - фоновые процессы —
presentation/background_processes/.
Исходящие внешние контракты и паспорта исходящих адаптеров в этот слот не помещать. Формировать поддерево «Презентационный слой» в порядке: HTTP API, входящие сообщения, фоновые процессы. Не создавать для этих входов параллельные корневые разделы.
Выбор специализированного скила
- Для HTTP API использовать
http-api-documentation-writing. - Для входящих сообщений использовать
message-consumer-documentation-writing. - Для периодических и постоянно работающих внутренних процессов использовать
background-process-documentation-writing; считать их внутренними driving entry points presentation, не смешивая с HTTP и message consumer-контрактами. - Для нескольких видов входа сначала определить общие требования здесь, затем документировать каждый внешний контракт своим скилом.
Исходящие сообщения и технологические клиенты являются адаптерами выходной стороны и не входят в эти скилы.
Рабочий процесс
- Определить потребителей, назначение и виды внешнего взаимодействия.
- Найти согласованные application-операции, входы, результаты и публичные исходы.
- Разделить общие требования и транспортно-специфичные контракты.
- Определить владельца каждой модели, правила и нормативного документа.
- Выбрать специализированные скилы и структуру документов.
- Проверить сквозные идентичность, область вызова, корреляцию и совместимость.
- Проверить отсутствие противоречий между транспортами и application-слоем.
Использовать документацию как основной источник требований. Код изучать только при адаптации существующей документации, после отдельного разрешения пользователя.
Общие требования
Для каждой внешней точки входа фиксировать:
- потребителя и назначение;
- публичную application-операцию и ссылки на её контракты;
- собственные presentation-модели;
- источники внешних сведений и доверенного контекста;
- преобразование входа и результата;
- транспортную валидацию отдельно от бизнес-правил;
- внешнее представление публичных application-исходов;
- повтор, совместимость и значимую наблюдаемость;
- готовность и открытые вопросы.
Стабильное обозначение документа строить как иерархию
<контекст>.<слой>.<уточнения...>. После слоя количество сегментов не
ограничивать. Для presentation включать вид взаимодействия, область доступности и
версию, когда они различают контракты.
Согласование решений
Стабильные обозначения
Каждый сегмент обозначает один уровень смысла: вид взаимодействия, область, версию, ресурс, действие или модель. Не склеивать ресурс и действие и не пропускать ресурс. Одинаковый контракт во всех presentation-документах имеет одно обозначение независимо от имени файла; профильный скил уточняет допустимые сегменты конкретного взаимодействия.
Предлагать пользователю отсутствующие транспортные ограничения и варианты, но не делать их нормативными без согласования. За один подход задавать до пяти коротких, до трёх средних либо один-два крупных связанных вопроса.
Каждый содержательный документ завершать разделом ## Открытые вопросы. Если
вопросов нет, писать Открытых вопросов нет.. Не объявлять документ готовым,
если реализация потребует нового продуктового решения.
Проверка
- Каждый контракт принадлежит одному владельцу и имеет нормативный документ.
- Внешние модели отделены от application DTO.
- Все внешние значения и результаты трассируются до application-контрактов.
- Domain не зависит от presentation и не раскрывается через него напрямую.
- Общие правила не расходятся между транспортами.
- Специализированные документы созданы соответствующими скилами.
- Навигация и ссылки ведут только к актуальным документам.
- Все входящие и внутренние driving entry points находятся под
presentation/и представлены одним навигационным поддеревом.