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

GET /api/v1/reward-rules/{ruleId} — Карточка правила вознаграждения

Точечное чтение одного правила вознаграждения застройщика — экран редактирования/просмотра правила в админке застройщика.

Назначение​

Менеджер застройщика открывает правило для просмотра или правки (правка — update-reward-rule.md). Owning-контекст — rewards, дом полей — domain/reward-rule.md. Feature group — rules.

Metadata​

ПолеЗначение
Сервис/контекстrewards
API areadeveloper-admin
Feature grouprules
Статусdraft
Документdocs/06-services/rewards/api/admin/get-reward-rule.md

Актор и доступ​

ПроверкаЗначение
Actor typeUser (менеджер компании-застройщика)
Auth policy / Permissionsrewards.rules.view
Scope (RBAC)организация: компания Type = Developer
Record-levelне применяется
Tenant isolationTenantId из claims; правило чужого tenant-а невидимо (интерсептор) → 404
Auditnone (read)

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/v1/reward-rules/{ruleId}
Success status200
Idempotency headerне применяется (read)
Correlationсквозной trace через заголовок traceparent

Входные данные / параметры запроса​

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
TenantIdidentity claims (tenant_id)GuidДаRequiredTenant isolation
RuleIdroute {ruleId}GuidДаRequired, непустой Guid—

Модель ответа GetRewardRuleQueryResult​

Обёртка над RewardRuleModel (дом — README.md) без дельты: единственное поле Rule.

ПолеТипОбязательностьИсточникMaskingОписание
RuleRewardRuleModelДаRewardRuleEntity—Полная проекция правила, включая Conditions и Version (для optimistic-конкуренции последующей мутации).

Алгоритм​

Точечное чтение. Менеджер застройщика с правом rewards.rules.view запрашивает правило по RuleId в scope своей организации. RuleId должен быть непустым (!= Guid.Empty) и корректным Guid — иначе ValidationError (400; некорректный формат отклоняется до обращения к хранилищу). Правило ищется в пределах tenant-а застройщика; читаются все статусы, включая Archived (история). Если правило не найдено или принадлежит другому tenant-у → REWARDS_RULE_NOT_FOUND (404; существование чужого правила не раскрывается). Иначе возвращается полная проекция RewardRuleModel (включая Conditions и Version для последующей optimistic-конкуренции) → 200. Freshness — source of truth, без кэша: отдаётся актуальное состояние на момент запроса.

Ошибки и failure modes​

КодHTTP statusУсловиеСообщениеRetry
ValidationError400RuleId пуст (Guid.Empty) или некорректный Guid«Некорректный идентификатор правила»no retry
REWARDS_RULE_NOT_FOUND404Правило не существует или принадлежит другому tenant-у«Правило не найдено»no retry

Общие коды — README.md.

Acceptance-критерии​

  • Happy path. Дано: правило существует в tenant-е актора, у актора есть rewards.rules.view. Когда: GET /api/v1/reward-rules/{ruleId}. Тогда: 200, полная проекция RewardRuleModel с актуальным Version (для последующей optimistic-конкуренции) и Conditions.
  • Архивное правило доступно. Дано: правило в статусе Archived. Когда: GET. Тогда: 200 — архив читается как история (в отличие от списков «по умолчанию неархивные»).
  • Чужой tenant / не существует. Дано: RuleId принадлежит другому застройщику либо отсутствует. Когда: GET. Тогда: 404 REWARDS_RULE_NOT_FOUND (существование чужого правила не раскрывается).
  • Пустой/некорректный идентификатор. Дано: RuleId = Guid.Empty или неразбираемый Guid. Когда: GET. Тогда: 400 ValidationError (до обращения к хранилищу).
  • Нет права. Дано: у актора нет rewards.rules.view. Когда: GET. Тогда: 403 FORBIDDEN.

Совместимость и наблюдаемость​

  • Модель — общий RewardRuleModel: изменения только additive.
  • Logs: TenantId, RuleId; metrics: rewards_api_request_duration_seconds{route}; traces: OTel; dashboard rewards-overview; runbook — не применяется.

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

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

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