Nemagu Документирование входящих сообщений
Документировать сообщение как внешнюю точку входа presentation, а не как цикл воркера или конфигурацию брокерного клиента.
Перед работой читать consumer-contract.md и review-checklist.md.
Граница
Одно сообщение по умолчанию вызывает одну публичную application-операцию. Envelope и payload являются внешними моделями и не передаются как application DTO. Application-результат не публикуется автоматически; исходящее сообщение имеет собственный контракт и адаптер.
Не описывать подключение, пул соединений, параллелизм runtime, библиотеку, хранилище дедупликации или жизненный цикл процесса.
Размещение и навигация
Размещать документы входящих сообщений внутри presentation/messages/.
Группировать по внешнему источнику или устойчивой группе контрактов, когда это
помогает навигации. Исходящие сообщения сюда не помещать: они принадлежат
external-contracts/outgoing/.
Формировать только поддерево «Входящие сообщения», начиная с
presentation/messages/README.md. Не создавать общий корень messages или
external-contracts/messages, смешивающий направления.
Рабочий процесс
Стабильные обозначения
Использовать схему
<контекст>.presentation.messages.<источник>.<ресурс или факт>.<действие или версия>.
Источник, ресурс и действие являются отдельными смысловыми сегментами; не
склеивать их и не пропускать ресурс. Одинаковый контракт сообщения во всех
документах имеет одно обозначение независимо от адреса и имени файла.
- Определить владельца сообщения, отправителя, бизнес-факт и потребителей.
- Согласовать транспорт и адресацию, если они входят в контракт.
- Разделить envelope, payload и транспортные метаданные.
- Определить доверие, идентичность, область и корреляцию.
- Сопоставить каждое значение с application-входом.
- Сопоставить публичные application-исходы с семантикой обработки.
- Согласовать повторы, идемпотентность, актуальность, порядок и совместимость.
- Добавить примеры и проверить готовность.
Использовать документацию как источник требований. Код читать только при адаптации существующей документации и после отдельного разрешения пользователя.
Готовность
Контракт готов, если реализация не выбирает самостоятельно источник, схему,
доверие, преобразование, application-операцию, исход, повтор, порядок, актуальность
или совместимость. Каждый документ завершать разделом ## Открытые вопросы.
Разделы Назначение, Источник и Доверие оформлять отдельно. Один файл
описывает один ресурс или одно семейство однородных фактов с одной моделью;
проекции разных объектов и команды создания агрегатов не объединять в файл.