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

Отчет/Export: Сводка вознаграждений агентства за период (agency-rewards-period-summary)

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

Назначение​

Даёт владельцу/руководителю агентства сводную картину за период: кто из агентов сколько принёс и сколько ему причитается/выплачено, сколько агентство удержало себе. Decision value — расчёт зарплатных итогов, оценка эффективности агентов, планирование выплат. Детальная раскладка по сделкам — парный отчёт agency-rewards-by-employee-per-deal.md. Owning service — rewards.

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

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

Доступ​

ActorPermissionTenant/Brand scopeAudit
владелец/руководитель агентстваrewards.commission.view-allTenantId = CompanyId агентства из claims; fail-closedExportSensitive — постановка, выдача ссылки, исход генерации

Исходные Source Data​

ИсточникВладелецТипFreshnessJoin key
rewards.commission_accrualsrewardssource of truthстрого согласованоTenantId + DealCompletedAt (период), группировка по AgentUserId
rewards.commission_distributionsrewardssource of truth (строки Agent/Agency — ../domain/commission-accrual.md)строго согласованоAccrualId
Пользователи identity (ФИО агентов)identityenrichment при генерации (не хранится в rewards)на момент генерацииAgentUserId

Фильтры AgencyRewardsPeriodSummaryFilterModel​

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

ПолеТипОбязательностьDefaultОграничения
TenantIdGuidДаidentity claimsRequired; не из UI
PeriodFromDateTimeOffsetДа—начисления: DealCompletedAt >= PeriodFrom
PeriodToDateTimeOffsetДа—> PeriodFrom (исключительно); диапазон ≤ 1 года
AgentUserIdGuid?Нетвсе агентысводка только по этому агенту (одна строка)

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

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

ПолеТипОбязательностьРасчетMasking
AgentFullNamestringДаenrichment identity по AgentUserId (на момент генерации)—
DealsCountintДаcount начислений агента за период со статусом ≠ Cancelled—
CancelledCountintДаcount отменённых начислений (справочно)—
GrossTotaldecimalДаΣ CommissionAmount начислений (≠ Cancelled) — «начислено»Financial
AgentShareTotaldecimalДаΣ Amount строк Agent (начисления Confirmed/MoneyReceived/Paid) — причитается агентуFinancial
AgencyRetainedTotaldecimalДаΣ Amount строк Agency — «удержано агентством»Financial
PendingConfirmationTotaldecimalДаΣ CommissionAmount начислений в PendingConfirmation (gross; распределения ещё нет) — «ожидает подтверждения»Financial
ConfirmedShareTotaldecimalДаΣ Amount строк Agent начислений в Confirmed — «подтверждено, деньги не получены»Financial
MoneyReceivedShareTotaldecimalДаΣ Amount строк Agent начислений в MoneyReceived — «получено, готово к выплате» (гейт ADR-0067 пройден)Financial
PaidShareTotaldecimalДаΣ Amount строк Agent начислений в Paid — «выплачено»Financial

Контроль сходимости строки: ConfirmedShareTotal + MoneyReceivedShareTotal + PaidShareTotal = AgentShareTotal (доля агента существует только с Confirmed).

Модель Totals AgencyRewardsPeriodSummaryTotalsModel​

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

ПолеТипОбязательностьРасчетPrecision
AgentsCountintДаcount строк (агентов с начислениями за период)целое
DealsCountintДаΣ DealsCountцелое
GrossTotaldecimalДаΣ GrossTotalscale 2, banker's
AgentShareTotaldecimalДаΣ AgentShareTotalscale 2
AgencyRetainedTotaldecimalДаΣ AgencyRetainedTotalscale 2
PendingConfirmationTotaldecimalДаΣ PendingConfirmationTotalscale 2
ConfirmedShareTotaldecimalДаΣ ConfirmedShareTotalscale 2
MoneyReceivedShareTotaldecimalДаΣ MoneyReceivedShareTotalscale 2
PaidShareTotaldecimalДаΣ PaidShareTotalscale 2

Формат Export-а​

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

ColumnЗаголовокТипФорматNullableИсточник
AgentFullNameАгентstringтекстНетAgencyRewardsPeriodSummaryRowModel.AgentFullName
DealsCountСделокint# ##0Нет.DealsCount
GrossTotalНачислено (gross)decimal# ##0.00Нет.GrossTotal
AgentShareTotalДоля агентаdecimal# ##0.00Нет.AgentShareTotal
AgencyRetainedTotalУдержано агентствомdecimal# ##0.00Нет.AgencyRetainedTotal
PendingConfirmationTotalОжидает подтвержденияdecimal# ##0.00Нет.PendingConfirmationTotal
ConfirmedShareTotalПодтвержденоdecimal# ##0.00Нет.ConfirmedShareTotal
MoneyReceivedShareTotalПолученоdecimal# ##0.00Нет.MoneyReceivedShareTotal
PaidShareTotalВыплаченоdecimal# ##0.00Нет.PaidShareTotal
CancelledCountОтменено (шт.)int# ##0Нет.CancelledCount

Сортировка строк: AgentShareTotal DESC (самые результативные агенты сверху), затем AgentFullName ASC.

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

  1. Постановка задачи, permission rewards.commission.view-all, tenant scope, лимиты, audit — ../api/agency/create-rewards-export.md.
  2. Фоновый исполнитель читает начисления tenant-а за период со строками распределения (согласованный снапшот), агрегирует по AgentUserId.
  3. Обогащение ФИО агентов из identity (batch по уникальным id; не найден — id в ячейку, warn-лог).
  4. Проверка лимита строк (≤ 100 000 — для сводки практически недостижим: строк ≤ числа агентов агентства).
  5. Формирование строк и totals; контроль сходимости каждой строки и totals (расхождение — дефект целостности, задача → Failed, алерт).
  6. Сериализация XLSX → приватное объектное хранилище (retention 7 дней); задача → Completed; финальная audit-запись. Скачивание — ../api/agency/get-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=period_summary,result}
Logsпостановка / генерация / выдача ссылки / истечение / отказ — с актором и фильтрами; суммы не логируются (Financial)
Tracestraceparent, TenantId, JobId
AuditExportSensitive на постановку, выдачу ссылки и исход генерации

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

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

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