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

GET /api/v1/platform/referral-payout-orders — Список реферальных платёжных поручений

Постраничная история реферальных выплат платформы: поручения Kind = ReferralReward (tenant — компания ПИН) с номерами, периодами, суммами и статусами (ожидается / выплачено / отклонено) — domain/payout-order.md. Агентский аналог — ../agency/list-payout-orders.md.

Назначение​

Оператор ПИН просматривает реферальные поручения: черновики в работе, переданные в бухгалтерию (PendingPayment), выплаченные (Paid) и отклонённые (Rejected) — с фильтрами по статусу и периоду. Партнёр видит только свои начисления и выплаты по rewards.referral.view-own (record-level, partner-область). Feature group — referral-payouts.

Metadata​

ПолеЗначение
Сервис/контекстrewards
API areaplatform
Feature groupreferral-payouts
Статусdraft
Документdocs/06-services/rewards/api/platform/list-referral-payout-orders.md

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

ПроверкаЗначение
Actor typeUser (оператор ПИН)
Auth policy / Permissionsrewards.payouts.manage (платформенный scope)
Scope (RBAC)платформа
Tenant isolationвыборка ограничена tenant-ом компании ПИН и Kind = ReferralReward — агентские поручения в этой области не отдаются (и наоборот: реферальные не видны agency-области)
Auditread-sensitive (суммы выплат): в trace — actor + фильтры + TotalCount; суммы не логируются

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/v1/platform/referral-payout-orders
Success status200
Correlationсквозной trace через заголовок traceparent

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

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
StatusqueryPayoutOrderStatus?Нетenum Draft/PendingPayment/Paid/Rejected/Cancelled—
CreatedFromqueryDateTimeOffset?Нетнижняя граница CreatedAt (включительно)—
CreatedToqueryDateTimeOffset?Нетверхняя граница CreatedAt (исключительно); > CreatedFrom, если обе заданы—
PeriodToqueryDateTimeOffset?Нетфильтр по концу расчётного периода: PayoutOrder.PeriodTo <= PeriodTo—
Page / PageSizequeryintНетpaging-конвенция — README.md (Page >= 1, PageSize 1..100)—

Модель ответа — постраничный список PayoutOrderModel​

Постраничный ответ: Items (список PayoutOrderModel), Page, PageSize, TotalCount. Проекция PayoutOrderModel — дом README.md «Общие контрактные модели».

Дельта проекции для списка: у всех строк Kind = ReferralReward; позиции (PayoutOrderItemModel, RecipientUserId = партнёр) в списке отдаются пустой коллекцией — детализация состава загружается запросом одного поручения (используется операциями утверждения/выплаты: approve-referral-payout-order.md, mark-referral-payout-order-paid.md).

Алгоритм​

Тривиальное постраничное чтение: проверить право rewards.payouts.manage платформенного scope (иначе FORBIDDEN) и параметры фильтра (enum Status, CreatedTo > CreatedFrom, paging — иначе ValidationError); прочитать страницу поручений tenant-а ПИН с Kind = ReferralReward по фильтрам (Status, границы CreatedAt, PeriodTo) с сортировкой CreatedAt DESC (опорные индексы — ix_payout_orders_tenant_kind, ix_payout_orders_tenant_status, ix_payout_orders_created_at); спроецировать в PayoutOrderModel (Items = []) и вернуть 200. Чтение строго согласовано с записью: только что утверждённое/выплаченное поручение сразу видно с новым статусом.

Ошибки и failure modes​

Специфичных REWARDS_*-кодов у read-операции нет; общие коды (ValidationError 400 — Status вне enum, CreatedTo <= CreatedFrom, PageSize вне 1..100; FORBIDDEN 403; UNAUTHORIZED 401) — дом README.md «Общие ошибки».

Acceptance criteria​

  • AC-1 (история реферальных выплат). Given у платформы есть реферальные поручения в разных статусах; When оператор запрашивает список без фильтра; Then 200, поручения по CreatedAt DESC, у каждого — Number, Kind = ReferralReward, Status, PeriodFrom/To, TotalAmount, ItemsCount, даты переходов; Items = [].
  • AC-2 (фильтры). Given те же данные; When Status = Paid и/или границы CreatedFrom/CreatedTo (или PeriodTo); Then в выдаче только строки под все условия; CreatedFrom включителен, CreatedTo исключителен.
  • AC-3 (изоляция видов). Given есть агентские поручения (Kind = AgencyCommission) разных агентств; When запрошен список; Then их в выдаче нет — область отдаёт только реферальные поручения tenant-а ПИН.
  • AC-4 (детализация — отдельным запросом). Given строка с ItemsCount = 7; When оператор открывает поручение; Then позиции по партнёрам грузятся запросом одного поручения (в списке Items = []).
  • AC-5 (пустой результат / валидация). Given нет поручений под фильтр или Page за последней — 200, Items = [], корректный TotalCount; Given Status вне enum или CreatedTo <= CreatedFrom — ValidationError (400).
  • AC-6 (доступ). Given актор без rewards.payouts.manage платформенного scope (в т.ч. руководитель агентства, партнёр); When запрос; Then FORBIDDEN (403); партнёру — только его собственные начисления/выплаты через partner-область (record-level PartnerUserId).
  • AC-7 (свежесть). Given поручение только что выплачено (mark-referral-payout-order-paid.md); When сразу запрошен список; Then статус Paid уже виден (строгая согласованность чтения внутри rewards).

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

  • PayoutOrderModel — общая проекция из README.md: новые optional-поля — additive; новые значения PayoutOrderStatus/PayoutOrderKind — по unknown-enum-правилу.
  • Logs: фильтры (Status, границы дат), TotalCount (суммы не логируются); metrics: rewards_api_request_duration_seconds{route}; traces: OTel, correlation через traceparent; dashboard rewards-overview.
  • НФТ (ADR-0056): единицы реферальных поручений в месяц — история измеряется десятками строк в год; выборка без джойна позиций; целевая латентность p95 < 250 мс.

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

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

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