Перейти к основному содержимому

Правила документирования Chessboard.Panoramas

Назначение​

Описание структуры документации микросервиса Panoramas и правил оформления постановок задач для wiki.

Структура документации​

  • api — по одному файлу на контроллер (Admin: PanoramaPoints, QueueTasks; Developers: обзор-заглушка).
  • domain — по одному файлу на команду/запрос (Admin Domain, Developers Domain). Каждый документ — постановка задачи с секциями: Назначение, Цель, Входные данные, Результат, Бизнес-логика, Валидация, Ограничения, События, Связанные сущности, API.
  • database — по одному файлу на сущность (entities), отдельно owned types и один файл enums. Ссылки между сущностями и типами (FK, «Используется в»).
  • events — Kafka consumers (входящие события из Talent.Chessboard.Events), MediatR-уведомления (AfterFileUploaded, AfterFileDeleted).
  • sagas — FileUpload, FileDelete (триггеры, payload, шаги).

CQRS-блоки в Domain​

В описании метода явно выделяются три блока:

  1. Command / Query (Входные данные) — таблица полей с обязательностью (Обязательное / Nullable).
  2. Result (Выходные данные) — таблица полей ответа. Для списков: поле Entries (коллекция или PagingResult), элементы — тип ResultEntry. Пагинация — PagingQuery (take, offset).
  3. Handler (Бизнес-логика) — пошаговый алгоритм без привязки к коду (без упоминания MediatR, класса handler).

Шаблоны формулировок бизнес-логики​

  • Получение по Id: Получить сущность X из таблицы XEntity по полю = значение из request. Если не найдена — вернуть ошибку. Получить связанные сущности по условию. Сформировать объект результата. Вернуть результат клиенту.
  • Поиск с пагинацией: Найти сущности X из XEntity по условиям из Query. PagingQuery: take, offset. Получить идентификаторы связанных сущностей; загрузить связанные сущности по Id. Сформировать результат, сопоставить Id и модели. Вернуть результат клиенту.
  • Создание: Провалидировать зависимости (получить по Id из БД). Если не найдены — ошибка. Создать сущность X в таблице XEntity, заполнив поля. При необходимости отправить Kafka event через outbox. Сформировать результат. Вернуть результат клиенту.

Обязательность полей​

В таблицах везде указывать Обязательное или Nullable.

Диаграммы​

  • Mermaid: flowchart (алгоритмы Domain), erDiagram (связи сущностей), sequenceDiagram (саги). Либо PlantUML при необходимости.
  • В Mermaid: camelCase для ID узлов, кавычки для подписей со спецсимволами.

Ссылки​

Использовать префикс /chessboard/panoramas/ для ссылок внутри документации Panoramas, например: AddPanoramaShootingPointCommand.

Формат для wiki​

Каждый документ по методу (API, Domain, Kafka consumer, saga) оформлен как законченная постановка в markdown. При вставке в wiki при необходимости можно обернуть содержимое в блок кода (markdown) для сохранения разметки.

Общее руководство​

Руководство по написанию документации — язык, стиль, структура документа, форматирование, именование.