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

Правила Документирования Алгоритма

Каноничная структура раздела «Алгоритм» для любой операции (API-метод, consumer, background job, use case). Раздел описывает поведение — что операция делает по шагам на уровне бизнес-логики, happy path и negative paths. Уровень изложения — по Уровню изложения ТЗ.

Зачем​

Алгоритм — главная ценность документа операции. Он отвечает: что делает операция, какую сущность по каким условиям читает/проверяет, какие бизнес-правила применяет, что создаёт/меняет/удаляет, какие факты/события фиксирует и что возвращает — и что происходит при каждом отказе. Это постановка для аналитика и разработчика, а не псевдокод: никаких имён классов/хендлеров, вызовов репозиториев, монады результата и транзакций SDK.

Структура шагов​

Заполняй нумерованными шагами. Неприменимый шаг опускается, а не помечается «не применяется». Шаги записи (5–7) в read-операциях не пишутся вовсе. Порядок:

  1. Контекст и доступ. Кто выполняет операцию (актор), в каком scope/tenant; какие права требуются.
  2. Проверка входа и предусловий (каждый пункт явно, при нарушении — какой код ошибки):
    • формат/диапазоны/enum входных полей → ошибка валидации;
    • существование сущности по её бизнес-ключу/id → если не найдена, какой код ошибки (или это upsert — тогда отсутствие допустимо);
    • допустимость состояния — текущий статус сущности разрешает операцию (перечислить допустимые);
    • принадлежность/scope — tenant, владелец/группа (record-level), согласованность связей.
  3. Что читаем. Какие сущности и по каким условиям загружаем и зачем (напр. «карточка проекта — для проверки инварианта до записи»). Списки/поиск — по каким фильтрам/сортировке/пагинации.
  4. Бизнес-правила и переходы. Инварианты (INV-*), переходы статуса From → To с условием, расчёты; маппинг поле-в-поле: для каждого выходного/сохраняемого поля — источник (вход/загруженная сущность/ вычисление).
  5. Что меняется (только операции записи). Какие сущности создаются/обновляются/удаляются и в каком порядке; правила конкурентного доступа — как бизнес-условие («правка не должна затирать чужую»).
  6. Какие факты/события фиксируются (только если есть). Доменные и интеграционные события: имя события, топик, из каких полей собирается снапшот, кто потребители.
  7. Согласованность (только операции записи). Что меняется в одном согласованном изменении (атомарно) — бизнес-формулировкой, без имён транзакций SDK.
  8. Результат. Что возвращает операция (модель/статус); для чтения — актуальность (freshness) и правила маскирования чувствительных полей.

Правила стиля​

  • Пиши доменными именами: сущность, поле, статус, enum, инвариант, код ошибки, топик, событие. Не используй имён классов/хендлеров/валидаторов, вызовов репозиториев, Result.Fail(...), транзакций SDK.
  • Коды ошибок называй в шаге и дублируй в таблице «Ошибки»; не показывай форму Result.Fail(CODE).
  • Каждый шаг — happy path; для каждой ветки отказа явно указывай исход (какой код ошибки / деградация).
  • Диаграмма — опциональна; если рисуешь, участники — бизнес/доменные роли (актор, сервис, витрина, внешняя система), не репозитории/хендлеры. Для тривиального CRUD диаграмму не рисуй.

Мини-пример (фиксация клиента, CRM)​

  1. Контекст и доступ. Операцию выполняет агент; tenant — его агентство; требуется право фиксировать клиента.
  2. Проверка. Объект существует и его статус ∈ {Available, Reserved}; инвестор существует; агент принадлежит агентству (scope); на пару (агент, инвестор, объект) ещё нет активной фиксации — иначе отказ CRM_FIXATION_ALREADY_EXISTS.
  3. Что читаем. Объект и инвестора — для проверок выше.
  4. Правила. Создаём фиксацию (инвариант «одна активная фиксация на пару»), статус None → Active.
  5. Что меняется. Появляется запись фиксации.
  6. События. Публикуется ClientFixated (топик pin.crm.client-fixations.v1) — потребители: rewards, dev-stats.
  7. Согласованность. Фиксация и факт её создания фиксируются в одном согласованном изменении.
  8. Результат. Идентификатор фиксации, её статус и дата.

Обратные ссылки​

Автоссылки: где используется этот документ.

Связанные документы​