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

US-реестр: Финансовый блок ПИН (US-FIN)

Назначение​

Реестр user stories платформенных акторов ПИН контекста rewards — что настраивают и делают Менеджер ПИН и финансовый оператор ПИН вокруг денег вознаграждений: акт поступления средств как гейт всех выплат (каскад одобрений), корректировка суммы начисления (gross) до гейта, настройка удержания платформы (0.25–1.50 п.п.) и индивидуальных условий по измерениям Застройщик / Проект / Планировка (и временных акций), реферальные ставки и реферальные начисления/выплаты. Все эти сущности живут вне tenant-модели — платформенный scope, кросс-tenant видимость (../domain/platform-receipt.md, ADR-0052). Каждая story даёт формулировку «как … хочу … чтобы …», приоритет, критерий приёмки и ссылки на покрывающие домены, операции, события и use-cases.

Metadata​

ПолеЗначение
ID-диапазонUS-FIN-01..16
РолиМенеджер ПИН (условия платформы, ставки, gross-корректировки) / финансовый оператор ПИН (акты поступления, реферальные поручения)
Контекстrewards (платформенный scope, кросс-tenant)
Статусdraft
ПриоритетыMust (гейт денег и удержание) / Should (индивидуальные условия, реферальные ставки, корректировки) / Could (акции, удобства)
Правило покрытияКаждая story обязана иметь ≥ 1 покрывающий домен-документ и ≥ 1 операционный документ (api/UC/событие); отсутствие покрытия = дыра traceability

Карта покрытия (обзор)​

Роль: Менеджер ПИН — монетизация и правила (US-FIN-01..08)​

Менеджер ПИН настраивает, сколько платформа зарабатывает на каждой сделке и реферале, и правит суммы начислений до момента получения денег. Условия и ставки применяются снапшотом на момент завершения сделки — их последующая правка не пересчитывает уже созданные начисления.

№User StoryПриоритетКритерий приёмкиПокрытие: доменПокрытие: API / UC / события
US-FIN-01Как Менеджер ПИН, я хочу задать глобальное удержание платформы в процентных пунктах ставки застройщика (0.25–1.50 п.п.), чтобы платформа получала свою долю с каждой сделки.MustСоздаётся запись условий с RetentionPercentagePoints ∈ [0.25; 1.50]; вне диапазона — отказ (INV-PT-1); глобальная запись (все измерения null) — страховочный уровень резолюции.../domain/platform-commission-terms.md — INV-PT-1, Global../api/platform/create-platform-terms.md; UC-RWD-007
US-FIN-02Как Менеджер ПИН, я хочу задать индивидуальные условия удержания по измерениям Застройщик / Проект / Планировка (и по конкретному агентству), чтобы монетизация отражала договорённости с застройщиками.ShouldУсловия задаются на пересечении осей объекта (DeveloperCompanyId → ProjectId → LayoutGroupId, сверху вниз) и агентства; ось заполняется top-down (INV-PT-5); резолюция выбирает наиболее специфичную активную запись на момент CompletedAt.../domain/platform-commission-terms.md — PlatformTermsScope, INV-PT-5../api/platform/create-platform-terms.md, ../api/platform/activate-platform-terms.md; UC-RWD-007
US-FIN-03Как Менеджер ПИН, я хочу проводить временные акции ПИН (пониженное удержание на срок) обычной записью условий с ограниченным периодом, чтобы не заводить отдельные промо-флаги.CouldАкция — запись с EffectiveFrom/EffectiveTo; периоды активных условий одной специфичности не пересекаются (INV-PT-2); по истечении периода резолюция автоматически возвращается к более широкой записи.../domain/platform-commission-terms.md — период, INV-PT-2../api/platform/create-platform-terms.md; UC-RWD-007
US-FIN-04Как Менеджер ПИН, я хочу активировать, досрочно завершать и архивировать условия удержания, чтобы управлять их жизненным циклом без потери истории.ShouldDraft → Active → Archived; в Active меняется только EffectiveTo (сокращение периода, INV-PT-3); архивная запись выведена из резолюции, но снятые снапшоты в начислениях живы.../domain/platform-commission-terms.md — статусы, INV-PT-3../api/platform/activate-platform-terms.md, ../api/platform/update-platform-terms.md, ../api/platform/archive-platform-terms.md
US-FIN-05Как Менеджер ПИН, я хочу видеть реестр условий удержания с их специфичностью и периодами, чтобы контролировать монетизацию и находить пробелы.ShouldСписок показывает измерения, RetentionPercentagePoints, период и статус; доступен только платформенному scope (rewards.platform-terms.view); агентствам сами условия не отдаются.../domain/platform-commission-terms.md — permissions../api/platform/list-platform-terms.md
US-FIN-06Как Менеджер ПИН, я хочу задавать реферальные ставки на 4 уровнях специфичности (партнёр×застройщик / партнёр / застройщик / глобально) со сроками действия, чтобы платить рефералам корректный процент.ShouldСтавка резолвится по «специфичное побеждает» на момент CompletedAt; периоды внутри одного уровня не пересекаются; снапшот ставки фиксируется в реферальном начислении.../domain/referral-rate-rule.md — уровни, срок; ../domain/referral-accrual.md — AppliedRateSnapshot../api/platform/create-referral-rate-rule.md, ../api/platform/activate-referral-rate-rule.md; UC-RWD-008
US-FIN-07Как Менеджер ПИН, я хочу управлять жизненным циклом реферальных ставок (обновить/активировать/архивировать) и видеть их реестр, чтобы поддерживать актуальность условий.ShouldDraft → Active → Archived с непересечением периодов внутри уровня; реестр показывает уровень, процент, период и статус.../domain/referral-rate-rule.md — статусы, непересечение../api/platform/update-referral-rate-rule.md, ../api/platform/archive-referral-rate-rule.md, ../api/platform/list-referral-rate-rules.md
US-FIN-08Как Менеджер ПИН, я хочу скорректировать сумму комиссионного начисления (gross) с обязательной причиной, пока деньги ещё не получены, чтобы исправить ошибку расчёта до необратимого гейта.ShouldКорректировка gross допустима в PendingConfirmation/Confirmed, пока начисление не в поручении и не в не-отменённом акте; скорректированная сумма > удержания ПИН (пул > 0); удержание Platform не пересчитывается; исходная сумма фиксируется в OriginalCommissionAmount; каждая корректировка оставляет append-only аудит-строку с причиной; после MoneyReceived gross неизменяем.../domain/commission-accrual.md — INV-10/11, CommissionAccrualAdjustmentEntity../api/platform/adjust-commission-accrual.md; UC-RWD-011

Роль: Финансовый оператор ПИН — гейт денег и выплаты (US-FIN-09..16)​

Финансовый оператор проводит факт получения денег от застройщика и запускает выплаты. Регистрация акта — единый необратимый гейт: до неё ни одна выплата (агентская или реферальная) недоступна.

№User StoryПриоритетКритерий приёмкиПокрытие: доменПокрытие: API / UC / события
US-FIN-09Как финоператор ПИН, я хочу завести акт поступления средств по пакетному платежу застройщика (номер RC-{yyyy}-{seq}, сумма поступления), чтобы связать пришедшие деньги с подтверждёнными начислениями.MustАкт создаётся Draft по одному застройщику (INV-RC-1); номер уникален per-year; сумма поступления берётся из платёжного документа.../domain/platform-receipt.md — Number, INV-RC-1../api/platform/create-platform-receipt.md; UC-RWD-010
US-FIN-10Как финоператор ПИН, я хочу набрать в акт подтверждённые начисления этого застройщика и видеть предпросмотр сходимости Σ позиций против суммы акта, чтобы собрать корректный состав.MustВ акт включаются только начисления в Confirmed того же застройщика (INV-RC-1), каждое — максимум в одном не-отменённом акте (INV-RC-3); предпросмотр показывает Σ позиций и расхождение с суммой акта.../domain/platform-receipt.md — INV-RC-1/2/3, позиции../api/platform/create-platform-receipt.md; UC-RWD-010
US-FIN-11Как финоператор ПИН, я хочу зарегистрировать акт и тем самым атомарно провести каскад одобрений, чтобы деньги стали доступны к выплате.MustПри Register (Σ позиций = сумме акта, INV-RC-2) в одном согласованном изменении: позиции Confirmed → MoneyReceived, связанные рефералки Pending → Approved, публикуются события получения денег; расхождение суммы/устаревшая позиция — отказ (SUM_MISMATCH/ITEM_STALE), состав пересобирается.../domain/platform-receipt.md — INV-RC-2/4, каскад; ../domain/referral-accrual.md — INV-RA-3../api/platform/register-platform-receipt.md; ../events/commission-money-received.md
US-FIN-12Как финоператор ПИН, я хочу понимать, что зарегистрированный акт неизменяем и не откатывается, чтобы ошибки исправлять компенсацией, а не разворотом.MustRegistered — терминальный: состав и поля не правятся (INV-RC-4); исправление — компенсирующим начислением/корректировкой следующим периодом; черновик можно отменить (Cancel), освободив начисления.../domain/platform-receipt.md — INV-RC-4, статусы../api/platform/register-platform-receipt.md; UC-RWD-010
US-FIN-13Как финоператор ПИН, я хочу видеть реестр актов поступления и подсвеченный возраст старейшего подтверждённого начисления без акта, чтобы не быть узким местом гейта.ShouldРеестр показывает акты со статусами и суммами; наблюдаемость даёт возраст старейшего Confirmed-начисления без акта (алерт при превышении порога — оператор блокирует выплаты).../domain/platform-receipt.md — наблюдаемость../api/platform/list-platform-receipts.md
US-FIN-14Как финоператор ПИН, я хочу сформировать и утвердить реферальное платёжное поручение по одобренным начислениям, чтобы выплатить вознаграждения партнёрам.ShouldПоручение Kind = ReferralReward (tenant — компания ПИН) собирает свободные реферальные начисления в Approved, группирует по партнёрам; Approve замораживает состав при ItemsCount ≥ 1.../domain/payout-order.md — ReferralReward, INV-1/6../api/platform/create-referral-payout-order.md, ../api/platform/approve-referral-payout-order.md, ../api/platform/list-referral-payout-orders.md
US-FIN-15Как финоператор ПИН, я хочу отметить реферальное поручение выплаченным (исполнение платежа вне платформы), чтобы каскадно закрыть начисления и провести дебет кошельков.ShouldMarkPaid из PendingPayment каскадит привязанные рефералки Approved → Paid, проставляет PaidAt, публикует событие статуса поручения; дебет счетов ReferralCommission — по событию (ADR-0065).../domain/payout-order.md — INV-7; ../domain/referral-accrual.md — INV-RA-5../api/platform/mark-referral-payout-order-paid.md; ../events/payout-order-status-changed.md
US-FIN-16Как Менеджер/оператор ПИН, я хочу вести реестр реферальных начислений: скорректировать сумму (с причиной, до выплаты) или отменить ошибочное начисление целиком, чтобы поддерживать финансовую корректность.ShouldКорректировка суммы допустима пока начисление свободно и не выплачено (Pending/Approved, INV-RA-6), оставляет append-only аудит-строку; отмена целиком — ManualCorrection (не способ поправить сумму); из Approved дельта/отмена компенсируются проводкой кошелька Correction.../domain/referral-accrual.md — INV-RA-6, ManualCorrection../api/platform/adjust-referral-accrual.md, ../api/platform/cancel-referral-accrual.md, ../api/platform/list-referral-accruals.md; UC-RWD-011

Зафиксированные ограничения покрытия​

USОграничениеПринято
US-FIN-01/02Удержание — только процентные пункты ставки застройщика, не процент от суммы комиссииМодель монетизации ADR-0066 (0.25–1.50 п.п.); политика агентства делит пул (gross − удержание)
US-FIN-08/16Корректировка суммы — first-class, не отмена/правка ставкиОбязательная причина + append-only аудит; после MoneyReceived gross неизменяем (ADR-0067 п.4)
US-FIN-11/12Гейт денег необратимРегистрация акта — атомарный каскад без отката; частичные оплаты акта вне scope v1 (ADR-0067)
US-FIN-14/15Исполнение платежей отложеноПолная структура поручений + ручной MarkPaid (решение №9 ТЗ); реквизиты — из profile при будущей интеграции
US-FIN-04/06Правка условий/ставок не пересчитывает начисленияПрименённые значения зафиксированы снапшотами на момент CompletedAt

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

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

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