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

Отчет/Export: Сводка реферальных вознаграждений за период (referral-rewards-period-summary)

XLSX-выгрузка реферальных вознаграждений: строка = один партнёр за период — число начислений, начислено (всего), ожидает подтверждения (Pending), одобрено к выплате (Approved), выплачено (Paid); плюс итоговая строка по всем партнёрам выборки. Генерируется асинхронной задачей (../api/partner/create-referral-rewards-export.md, ReportType = PeriodSummary) по конвейеру ADR-0041.

Назначение​

Даёт сводную картину реферальных вознаграждений за период: кто из партнёров сколько заработал и на какой стадии находятся суммы (ожидает денег застройщика / одобрено / выплачено). Аудитория двойная: партнёр видит свою единственную строку (личный итог за период), Менеджер ПИН — все строки (планирование реферальных выплат, оценка эффективности партнёрской программы). Детальная раскладка по сделкам — парный отчёт referral-rewards-by-partner.md. Owning service — rewards.

Классификация​

ПолеЗначение
Тип отчетаXLSX
Аудиторияреферальный партнёр (свой итог) / Менеджер ПИН (все партнёры)
ЧувствительностьFinancial/Sensitive — суммы вознаграждений и персональные итоги партнёров; PII приведённых инвесторов не выгружается
Freshness SLAсостояние rewards на момент генерации (строго согласованный снапшот OLTP)
Retentionфайл — 7 дней в приватном объектном хранилище; данные-источник — бессрочно (финансовая история)

Доступ​

Реферальные начисления вне tenant-модели (../domain/referral-accrual.md): scope разрешается по permission актора.

ActorPermissionОбласть выборкиAudit
реферальный партнёрrewards.referral.view-ownrecord-level: только PartnerUserId = ActorUserId (одна строка)ExportSensitive — постановка, выдача ссылки, исход генерации
Менеджер ПИНrewards.commission.view-allплатформенный scope: все партнёры; опциональный фильтр PartnerUserIdExportSensitive — постановка, выдача ссылки, исход генерации

Исходные Source Data​

ИсточникВладелецТипFreshnessJoin key
rewards.referral_accrualsrewardssource of truthстрого согласованоDealCompletedAt (период), группировка по PartnerUserId
Пользователи identity (ФИО партнёров)identityenrichment при генерации (не хранится в rewards)на момент генерацииPartnerUserId

Фильтры ReferralRewardsPeriodSummaryFilterModel​

Снимаются с задачи выгрузки (../api/partner/create-referral-rewards-export.md); фильтр Status к сводному отчёту не применяется (строка и так раскладывает суммы по стадиям) — заданный Status игнорируется с warn-логом.

ПолеТипОбязательностьDefaultОграничения
ActorUserIdGuidДаidentity claimsRequired; не из UI
Scopestring (own/all)Дапо permission актораown для rewards.referral.view-own; all для rewards.commission.view-all
PeriodFromDateTimeOffsetДа—начисления: DealCompletedAt >= PeriodFrom
PeriodToDateTimeOffsetДа—> PeriodFrom (исключительно); диапазон ≤ 1 года
PartnerUserIdGuid?Нетвсе партнёры (только Scope = all)при Scope = own игнорируется и жёстко замещается ActorUserId

Строка Отчета ReferralRewardsPeriodSummaryRowModel​

Одна строка = один партнёр (PartnerUserId), по которому за период есть хотя бы одно начисление. Отменённые начисления (Cancelled) в суммы не входят — только в справочный счётчик. Все суммы — в валюте начислений (CurrencyId, RUB-only по ADR-0048).

ПолеТипОбязательностьРасчетMasking
PartnerFullNamestringДаenrichment identity по PartnerUserId (на момент генерации)—
AccrualsCountintДаcount начислений партнёра за период со статусом ≠ Cancelled—
CancelledCountintДаcount отменённых начислений (справочно)—
AccruedTotaldecimalДаΣ Amount начислений (≠ Cancelled) — «начислено всего»Financial
PendingTotaldecimalДаΣ Amount начислений в Pending — «ожидает подтверждения» (деньги от застройщика ещё не получены)Financial
ApprovedTotaldecimalДаΣ Amount начислений в Approved — «одобрено к выплате» (гейт ADR-0067 пройден, ещё не выплачено)Financial
PaidTotaldecimalДаΣ Amount начислений в Paid — «выплачено»Financial

Контроль сходимости строки: PendingTotal + ApprovedTotal + PaidTotal = AccruedTotal (каждое неотменённое начисление ровно в одной стадии).

Модель Totals ReferralRewardsPeriodSummaryTotalsModel​

Итог по выборке = суммирование колонок всех строк (строка «Итого» под таблицей).

ПолеТипОбязательностьРасчетPrecision
PartnersCountintДаcount строк (партнёров с начислениями за период)целое
AccrualsCountintДаΣ AccrualsCountцелое
AccruedTotaldecimalДаΣ AccruedTotalscale 2, banker's
PendingTotaldecimalДаΣ PendingTotalscale 2
ApprovedTotaldecimalДаΣ ApprovedTotalscale 2
PaidTotaldecimalДаΣ PaidTotalscale 2
CancelledCountintДаΣ CancelledCountцелое

Контроль сходимости totals: PendingTotal + ApprovedTotal + PaidTotal = AccruedTotal.

Формат Export-а​

Лист XLSX summary; заголовки русские; суммы — числовой формат scale 2; шапка листа — период, область выборки (свои / все партнёры), время генерации (UTC).

ColumnЗаголовокТипФорматNullableИсточник
PartnerFullNameПартнёрstringтекстНетReferralRewardsPeriodSummaryRowModel.PartnerFullName
AccrualsCountНачисленийint# ##0Нет.AccrualsCount
AccruedTotalНачислено всегоdecimal# ##0.00Нет.AccruedTotal
PendingTotalОжидает подтвержденияdecimal# ##0.00Нет.PendingTotal
ApprovedTotalОдобрено к выплатеdecimal# ##0.00Нет.ApprovedTotal
PaidTotalВыплаченоdecimal# ##0.00Нет.PaidTotal
CancelledCountОтменено (шт.)int# ##0Нет.CancelledCount

Сортировка строк: AccruedTotal DESC (самые результативные партнёры сверху), затем PartnerFullName ASC. Для партнёра (Scope = own) выборка — ровно одна строка.

Процесс Генерации​

  1. Постановка задачи, разрешение scope по permission, лимиты, audit — ../api/partner/create-referral-rewards-export.md.
  2. Фоновый исполнитель читает начисления за период (record-level PartnerUserId при own; опциональный PartnerUserId при all), агрегирует по PartnerUserId — согласованный снапшот.
  3. Обогащение ФИО партнёров из identity (batch по уникальным id; не найден — id в ячейку, warn-лог).
  4. Проверка лимита строк (≤ 100 000 — для сводки практически недостижим: строк ≤ числа партнёров).
  5. Формирование строк и totals; контроль сходимости каждой строки и totals (расхождение — дефект целостности, задача → Failed, алерт).
  6. Сериализация XLSX → приватное объектное хранилище (retention 7 дней); задача → Completed; финальная audit-запись. Скачивание — ../api/partner/get-referral-rewards-export-job.md.

Лимиты​

ЛимитЗначениеОшибка
Max rows100 000 строкREWARDS_EXPORT_ROW_LIMIT_EXCEEDED (задача Failed)
Max date range1 годREWARDS_EXPORT_PERIOD_TOO_WIDE (400 на постановке)
Concurrent exports2 активные задачи на актораREWARDS_EXPORT_CONCURRENCY_LIMIT (429 на постановке)
ФорматыXLSX—

Наблюдаемость​

ТипПравило
Metricsrewards_export_duration_seconds, rewards_export_rows, rewards_export_jobs_total{report_type=referral_period_summary,result}
Logsпостановка / генерация / выдача ссылки / истечение / отказ — с актором, scope и фильтрами; суммы не логируются (Financial)
Tracestraceparent, ActorUserId, JobId
AuditExportSensitive на постановку, выдачу ссылки и исход генерации

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

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

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