Nemagu Документирование фоновых процессов
Описывать наблюдаемое поведение внутреннего процесса и его связь с публичной application-операцией без выбора языка, scheduler-а или runtime-библиотеки.
Перед работой читать process-contract.md и review-checklist.md.
Граница
Фоновый процесс инициирует application-операцию по времени или внутреннему условию. Он не является HTTP endpoint-ом или message consumer-ом. Application владеет сценарием и бизнес-исходами; процесс владеет запуском, ожиданием, ограничением времени, реакцией на технический результат и остановкой.
Не определять domain-правила, application DTO, реализацию портов, технологию расписания, event loop, классы или библиотеку.
Размещение и навигация
Считать фоновый процесс внутренним driving entry point presentation и размещать
его документацию в presentation/background_processes/. Раздел начинать с
README.md, отдельный процесс описывать отдельным файлом.
Формировать только поддерево «Фоновые процессы» внутри «Презентационного слоя».
Не создавать верхнеуровневый background_processes/ и не помещать процесс в
application-сценарии или паспорта адаптеров.
Рабочий процесс
Стабильные обозначения
Использовать схему
<контекст>.presentation.background_processes.<ресурс или назначение>.<действие>.
Назначение и действие являются отдельными смысловыми сегментами; не склеивать их
и не пропускать назначение процесса. Одинаковый процесс во всех документах имеет
одно обозначение независимо от имени файла или запускаемой операции.
- Определить цель, владельца и вызываемую application-операцию.
- Выбрать вид: однократный, периодический или постоянно работающий.
- Согласовать условия первого и следующих запусков.
- Определить перекрытие, параллелизм, тайм-аут и отмену.
- Сопоставить результаты операции с продолжением, повтором или остановкой.
- Определить startup, readiness, heartbeat и graceful shutdown.
- Зафиксировать восстановление после перезапуска и значимую наблюдаемость.
- Проверить готовность и открытые вопросы.
Оформлять Назначение и Операции отдельными разделами. Разные независимо
запускаемые роли — consumer, publisher, synchronizer и другие — описывать
отдельными процессами. В разделе наблюдаемости фиксировать собственные требования
процесса, не заменяя их требованием «соответствовать» документу логирования.
Код не использовать как источник требований. При адаптации существующей документации читать его только после отдельного разрешения пользователя.
Готовность
Документ готов, если реализация не выбирает самостоятельно момент запуска,
семантику расписания, перекрытие, тайм-аут, реакцию на исходы, остановку,
восстановление или состояние готовности. Каждый содержательный документ
завершать разделом ## Открытые вопросы.