US-реестр: Реферальный партнёр (US-PRT)
Назначение
Реестр user stories реферального партнёра контекста rewards — что видит и делает пользователь, приведший
инвестора, вокруг реферальных начислений (своя сумма, статус, применённая ставка и её срок), раздельного
реферального баланса кошелька и выгрузок своих вознаграждений. Партнёр — любой авторизованный
пользователь платформы (компания не требуется): его начисления живут вне tenant-модели, доступ —
record-level по PartnerUserId из claims (../domain/referral-accrual.md).
Каждая story даёт формулировку «как … хочу … чтобы …», приоритет, критерий приёмки и ссылки на покрывающие
домены, операции, события и use-cases.
Metadata
| Поле | Значение |
|---|---|
| ID-диапазон | US-PRT-01..13 |
| Роль | Реферальный партнёр (record-level по PartnerUserId) |
| Контекст | rewards (баланс — граница с wallet, ADR-0065) |
| Статус | draft |
| Приоритеты | Must (базовый ЛК партнёра) / Should (сверка и выгрузки) / Could (удобства) |
| Правило покрытия | Каждая story обязана иметь ≥ 1 покрывающий домен-документ и ≥ 1 операционный документ (api/report/UC/событие); отсутствие покрытия = дыра traceability |
Карта покрытия (обзор)
Роль: Реферальный партнёр (US-PRT-01..13)
Партнёр видит только свои начисления и баланс (фильтр всегда из claims, не из query); персональные данные
приведённого инвестора (InvestorUserId) ему не раскрываются; условия платформы и полные правила ставок ему
не отдаются — виден лишь применённый снапшот ставки в его начислении.
| № | User Story | Приоритет | Критерий приёмки | Покрытие: домен | Покрытие: API / отчёт / UC / события |
|---|---|---|---|---|---|
| US-PRT-01 | Как партнёр, я хочу видеть постраничный список своих реферальных начислений по сделкам приведённых инвесторов, чтобы контролировать заработанное. | Must | GET без фильтров возвращает только начисления с PartnerUserId = актор, сортировка DealCompletedAt DESC; чужие начисления не возвращаются ни при каких query-параметрах. | ../domain/referral-accrual.md — record-level PartnerUserId, индекс ix_referral_accruals_partner | ../api/partner/list-my-referral-accruals.md |
| US-PRT-02 | Как партнёр, я хочу видеть статус каждого начисления (начислено / одобрено / выплачено / отменено), чтобы понимать стадию вознаграждения. | Must | Каждая строка несёт Status ∈ {Pending, Approved, Paid, Cancelled} и относящиеся даты (ApprovedAt/PaidAt/CancelledAt); значения соответствуют enum ReferralAccrualStatus. | ../domain/referral-accrual.md — enum ReferralAccrualStatus, stateDiagram | ../api/partner/list-my-referral-accruals.md; статусные события — ../events/referral-accrual-status-changed.md |
| US-PRT-03 | Как партнёр, я хочу фильтровать начисления по статусу и периоду завершения сделки, чтобы быстро находить нужные. | Should | Фильтр Status и PeriodFrom/PeriodTo применяется по DealCompletedAt; нижняя граница включительна, верхняя исключительна; Status вне enum — ValidationError. | ../domain/referral-accrual.md — Status, DealCompletedAt, индексы | ../api/partner/list-my-referral-accruals.md |
| US-PRT-04 | Как партнёр, я хочу видеть применённую ставку (процент) и её область/срок из снапшота начисления, чтобы проверить, по какому проценту и на каком основании начислено. | Must | В строке — Percent, Scope (PartnerDeveloper/Partner/Developer/Global) и период EffectiveFrom/EffectiveTo из AppliedRateSnapshot; значения зафиксированы на момент CompletedAt и не меняются при последующей правке ставки. | ../domain/referral-accrual.md — AppliedRateSnapshot; ../domain/referral-rate-rule.md — область/срок | ../api/partner/list-my-referral-accruals.md |
| US-PRT-05 | Как партнёр, я хочу видеть базу расчёта (конечная цена сделки) и итоговую сумму вознаграждения, чтобы сверить начисление. | Must | В строке — BaseAmount (конечная цена) и Amount = BaseAmount × Percent / 100 (banker's, 2 знака, INV-RA-2); при скорректированной сумме показывается актуальный Amount. | ../domain/referral-accrual.md — BaseAmount, Amount, INV-RA-2/6 | ../api/partner/list-my-referral-accruals.md |
| US-PRT-06 | Как партнёр, я хочу видеть свой реферальный баланс кошелька отдельно от любых других начислений, чтобы понимать доступную к выплате сумму по реферальной программе. | Must | Баланс ведётся на отдельном счёте ReferralCommission (раздельные балансы одного пользователя); кредит появляется только по одобрению начисления (гейт MoneyReceived родителя), дебет — по выплате поручения. | ../domain/referral-accrual.md — авто-Approved по гейту | ../../wallet/README.md; ../../wallet/domain/wallet-account.md (ReferralCommission) |
| US-PRT-07 | Как партнёр, я хочу видеть историю операций своего реферального баланса (кредит при одобрении, дебет при выплате, корректировки), чтобы понимать, откуда сложился баланс. | Should | Каждая проводка счёта отражена записью журнала с основанием (SourceId начисления/поручения) и суммой; компенсации сумм — отдельной строкой Correction. | ../domain/referral-accrual.md — INV-RA-6 (компенсация дельты) | ../../wallet/domain/ledger-transaction.md; ../../wallet/events/wallet-transaction-recorded.md |
| US-PRT-08 | Как партнёр, я хочу понимать, что вознаграждение становится доступным к выплате только после того, как ПИН получил деньги от застройщика, чтобы верно оценивать сроки. | Must | Начисление переходит Pending → Approved только автоматически при регистрации акта поступления средств по родительскому комиссионному начислению; прямого перевода в Approved нет (INV-RA-3). | ../domain/referral-accrual.md — INV-RA-3; ../domain/platform-receipt.md — гейт | UC-RWD-009; UC-RWD-010 |
| US-PRT-09 | Как партнёр, я хочу получать уведомления при начислении, одобрении, выплате и изменении суммы вознаграждения, чтобы не пропускать важные события. | Should | При создании начисления, каждом переходе статуса и корректировке суммы из Approved партнёр получает уведомление с суммой и сделкой (без PII инвестора). | ../domain/referral-accrual.md — события создания/статуса/корректировки | ../events/referral-accrual-created.md, ../events/referral-accrual-status-changed.md → notifications |
| US-PRT-10 | Как партнёр, я хочу видеть, каким реферальным поручением и когда выплачено вознаграждение, чтобы сверять поступления. | Should | В выплаченной строке — номер поручения (PO-{yyyy}-{seq}) и PaidAt; выплата возможна только каскадом реферального поручения (Kind = ReferralReward), а не прямым переводом (INV-RA-5). | ../domain/referral-accrual.md — PayoutOrderItemId, INV-RA-5; ../domain/payout-order.md — Number | ../api/partner/list-my-referral-accruals.md |
| US-PRT-11 | Как партнёр, я хочу понимать причину отмены начисления, если оно отменено, чтобы не терять картину. | Could | Для Cancelled показывается CancelReason (DealCancelled/BondRevoked/ManualCorrection); отмена из Approved компенсирует ранее кредитованный баланс проводкой Correction. | ../domain/referral-accrual.md — enum ReferralCancelReason, INV-RA-5 | ../events/referral-accrual-status-changed.md; ../consumers/crm-deal-cancelled.md |
| US-PRT-12 | Как партнёр, я хочу выгрузить детальную Excel-таблицу своих реферальных вознаграждений (строка = начисление) за период, чтобы сверить личные выплаты. | Should | Асинхронная задача формирует XLSX только по своим начислениям (scope own из permission); скачивание — по короткоживущему signed URL; период ≤ 1 года, ≤ 2 активных задач; PII инвестора в файл не попадает. | ../domain/referral-accrual.md — снапшот ставки, статусы | ../reports/referral-rewards-by-partner.md; ../api/partner/create-referral-rewards-export.md, ../api/partner/get-referral-rewards-export-job.md |
| US-PRT-13 | Как партнёр, я хочу выгрузить сводку своих реферальных вознаграждений за период (итоги по статусам), чтобы видеть общую картину без построчной детализации. | Could | Сводная XLSX-задача даёт итоги (начислено / одобрено / выплачено / отменено) за период; те же лимиты и signed URL, что у детальной выгрузки. | ../domain/referral-accrual.md — статусы | ../reports/referral-rewards-period-summary.md; ../api/partner/create-referral-rewards-export.md |
Зафиксированные ограничения покрытия
| US | Ограничение | Принято |
|---|---|---|
| US-PRT-01/04 | Партнёру не отдаётся InvestorUserId (PII приведённого инвестора) | Маскирование в проекциях и выгрузках партнёра (../domain/referral-accrual.md, «Permissions / PII») |
| US-PRT-06/07 | Баланс и журнал ведёт не rewards, а wallet | rewards — источник фактов (начисления/статусы), wallet — учёт следствий по событиям (ADR-0065); раздельный счёт ReferralCommission |
| US-PRT-08/10 | Момент доступности денег — гейт, а не начисление | Approved только по регистрации акта поступления средств родителя (ADR-0067); выплата — только реферальным поручением |
| US-PRT-11 | Самореферал не оплачивается | Начисление не создаётся, если приведший = агент сделки (INV-RA-4); обход через вторую учётку — осознанное ограничение v1 |
Обратные ссылки
Автоссылки: где используется этот документ.
- Use Cases (2): US-реестр: Владелец агентства (US-OWN-AG), US-реестр: Финансовый блок ПИН (US-FIN)
- registries (1): Реестр use cases и user stories PIN
Связанные документы
- Дома полей: ../domain/referral-accrual.md (снапшот ставки, статусы,
INV-RA-1..6), ../domain/referral-rate-rule.md (область и срок ставки),
../domain/payout-order.md (
ReferralReward, номер поручения). - Основание — реферальная связь: ../../referral/domain/referral-bond.md.
- Гейт получения денег: ../domain/platform-receipt.md.
- Баланс и журнал: ../../wallet/README.md, ../../wallet/domain/wallet-account.md.
- Use cases: UC-RWD-009, UC-RWD-010.
- Смежные реестры US: настройка ставок и одобрений — user-stories-pin-finance.md.