Правила Документирования API Методов

Request/Response Модели

• У каждого API метода есть явная request model и response model.
• У каждого API метода явно указано, изменяет он данные или только читает (одна строка: «изменяет данные» / «только чтение»).
• Разделы Входные Данные и Выходные Данные обязательны и описываются таблицами.
• Таблица входных данных содержит поле, источник (route, query, body, header, identity context), тип, обязательность, описание, ограничения и откуда значение берется.
• Таблица выходных данных содержит поле, тип, обязательность, описание, источник вычисления и правила маскирования/безопасности.
• Типы object, json, jsonb, dictionary, map, payload, metadata, settings, filters без именованной typed модели запрещены.
• Даже методы чтения и списков не возвращают коллекцию напрямую.
• Response всегда является объектом с именованными свойствами.
• Коллекция возвращается как свойство response model.
• Метод, изменяющий данные, тоже возвращает response model.
• Для элементов коллекций используются отдельные item/view модели.
• Request/response модели описываются в файле метода API. Если модель переиспользуется между методами, она дополнительно выносится в models/<feature-group>/<model>.md.
• Модель запроса и ответа расписывается как таблица полей: имя, тип, обязательность, описание, ограничения, источник/маппинг.
• Порог «таблица vs список»: маппинг полей запроса/ответа при более чем 3–4 полях описывается ТАБЛИЦЕЙ с колонками поле | тип | обязательность | источник/маппинг | ограничения; опционально добавляется колонка Примечания для полезных пояснений (единицы, формат, связь с другим полем, правило маскирования). Для 1–3 полей допустим список.
• Если поле является nested object или коллекцией объектов, его модель описывается отдельной таблицей в том же файле или ссылкой на models/<feature-group>/<model>.md.
• Для каждого nullable поля указывается, когда оно отсутствует, когда равно null, кто имеет право видеть значение и как оно маскируется.
• Для каждого money/rate поля указывается decimal, scale/precision, округление и связанный CurrencyId, если поле выражено в валюте.
• Для стран, регионов, городов, валют и языков API принимает и возвращает id справочника handbook (типы id источника, не Guid): CountryId/CurrencyId/LanguageId — short, RegionId/CityId — long. ISO-коды — атрибуты записей handbook; в ответах они появляются только как явно описанные read-only поля или в snapshot-моделях (handbook/domain/snapshots.md).

Пример Таблицы Маппинга

Пример request model из 4 полей — оформляется таблицей (колонка Примечания опциональна):

Поле	Тип	Обязательность	Источник/маппинг	Ограничения	Примечания
LotId	Guid	да	route → ключ агрегата	существующий лот	должен существовать в каталоге
Amount	decimal	да	body	> 0, scale 2	выражено в валюте CurrencyId
CurrencyId	short	да	body, справочник handbook	существующая неархивная валюта	id справочника, не CurrencyCode
Comment	string?	нет	body	≤ 500 символов	null, если агент не заполнил

Actor, Permission И Scope

• Раздел Актор И Доступ должен явно перечислять actor type, auth policy, permissions, tenant scope, brand scope и MFA requirements.
• Нельзя писать проверить доступ; нужно указать конкретную permission, например catalog.lots.publish.
• Если операция вызывается system actor-ом, нужно указать источник: scheduler, Kafka consumer, provider callback adapter, reconciliation job.
• Для admin-операций указывается audit level: ReadSensitive, ManualDecision, SecurityDecision.

Алгоритм

• Раздел Алгоритм пишется как постановка задачи разработчику, а не как краткая заметка.
• Алгоритм должен быть пошаговым и детальным: какую сущность по какому ключу получить, какие permissions проверить, какие поля валидировать, какие значения вычислить, какие сущности создать/обновить/удалить, какие события зафиксировать.
• Для каждого шага указывается источник данных: request, route, identity context, owning service, reference lookup, existing entity или computed value.
• Для операций записи описывается, какие сущности меняются, какие события фиксируются и какой факт аудита появляется; конкурентный доступ формулируется как бизнес-условие («правка не должна затирать чужую»), идемпотентность — как поведение при повторном вызове.
• Для read методов явно описываются filters, tenant trimming, sorting, paging, projection freshness и masking.
• Нельзя писать алгоритм уровня "обновить запись" без перечисления конкретных полей и правил изменения.

Согласованность И Атомарность

• Для операций записи (mutation, callback, обработчик события, фоновая задача) описывается, что меняется в одном согласованном изменении — бизнес-формулировкой, без деталей транзакций.
• Перечисляются сущности и факты (запись сущности, аудит, зафиксированное событие), которые появляются атомарно: либо всё, либо ничего.
• Если внешний вызов выполняется до или после фиксации изменения, это описывается отдельно с поведением при сбое (повтор/сверка).
• Согласованность между сервисами обеспечивается сагой или компенсацией, а не распределённой транзакцией (если иное явно не утверждено ADR).

Побочные Эффекты

• Раздел Побочные эффекты включается только если эффекты есть (события, внешние вызовы, проекции, уведомления); если их нет — раздел опускается.
• Для событий указываются имя события, топик, ключ и источник payload.
• Для внешних вызовов указываются внешняя система, вызываемая возможность, таймаут, политика повторов и поведение при частичном успехе.
• Для кэша указываются ключи и правила инвалидации/перечитывания.
• Для read models указываются проекции/materialized views/индексы и синхронное или асинхронное обновление.
• Для уведомлений указываются канал, шаблон, получатель и правила подавления.

Observability

• Раздел Observability обязателен и содержит логи, метрики и tracing.
• Логи описываются по точкам: вход, ключевые шаги, controlled errors, unexpected errors.
• Метрики минимум: latency, error rate, throughput.
• Для критичных операций добавляются business metrics: счётчики бизнес-событий, счётчики переходов статусов, gauges очередей/backlog.
• Trace должен переносить correlationId; для event-driven операций также causationId.
• Sensitive fields в observability описываются как masked или excluded.

State Transitions

• Если метод меняет status/state, он обязан ссылаться на state transition table сущности или повторить переходы в файле метода.
• Нужно указать From, To, условие, инициатор, проверки и побочные эффекты.
• Нельзя менять status без проверки текущего состояния; при конкурентном изменении действует правило «правка не должна затирать чужую».
• Недопустимый переход возвращает типизированную ошибку и не порождает событий и записей аудита об изменении состояния.

DoR И DoD

• Разделы Definition Of Ready и Definition Of Done обязательны для новых или существенно измененных API methods.
• DoR проверяет полноту постановки до разработки.
• DoD проверяет соответствие реализации документации, наличие тестов, audit/logging, idempotency, race condition handling, edge cases, metrics и обновленной документации.

Lookup Методы

• Lookup методы предназначены для select, autocomplete, combobox, фильтров таблиц и коротких ссылок на сущности.
• Lookup list метод возвращает компактный список ResultEntry и не заменяет полноценный search/list метод сущности.
• Lookup by id метод возвращает объект ответа с полем Entry, а не сам ResultEntry напрямую.
• ResultEntry переиспользуется между сервисами как общая view model.
• Lookup list обычно принимает Term, параметры пагинации и типизированную модель фильтра, а возвращает страницу ResultEntry внутри именованного свойства response model.
• Lookup методы не должны отдавать secrets, raw PII, provider credentials, платежные реквизиты и большие вложенные объекты.
• Если lookup используется в admin UI для чувствительной сущности, метод требует отдельное permission и пишет audit при расширенном поиске по PII.
• Для lookup по справочникам handbook ResultEntry.Id всегда содержит id справочника, а не CurrencyCode, LanguageCode или CountryCode.

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

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

• algorithm-documentation-rules.md (1): Правила Документирования Алгоритма
• cross-cutting-document-requirements.md (1): Общие Требования К Документам
• strict-typed-documentation-rules.md (1): Правила Строгой Типизации Документации