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

US-реестр: Владелец агентства (US-OWN-AG)

Назначение​

Реестр user stories владельца/руководителя агентства контекста rewards — как агентство распределяет комиссию между агентом и собой (политика, agent-boost, per-deal перераспределение пула), выплачивает доли агентам и выгружает финансовую картину в Excel (детально по сотруднику×сделке и сводно за период). Все сущности агентства — в границах TenantId = CompanyId агентства (ADR-0052); управление — permission rewards.commission-policy.manage / rewards.payouts.manage/approve / rewards.commission.view-all. Каждая story даёт формулировку «как … хочу … чтобы …», приоритет, критерий приёмки и ссылки на покрывающие домены, операции, отчёты, события и use-cases.

Metadata​

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

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

Роль: Владелец агентства — политика распределения (US-OWN-AG-01..07)​

Политика определяет деление пула агентства (комиссия − удержание ПИН) между строками Agency (удержание агентства) и Agent (доля агента). Строка Platform (удержание ПИН) вне политики и неприкосновенна. У агентства одновременно одна активная политика; смена политики не пересчитывает уже подтверждённые начисления (в начислении хранится снапшот применённого правила).

№User StoryПриоритетКритерий приёмкиПокрытие: доменПокрытие: API / отчёт / UC / события
US-OWN-AG-01Как владелец агентства, я хочу задать политику распределения комиссии (удержание агентства в % или фиксированной суммой от пула), чтобы автоматически считать долю агента и удержание агентства.MustПравило DefaultRule задаёт Percent/FixedAmount (удержание агентства) либо AgentPercentOfPool/AgentPercentOfPrice (доля агента); agencyShare + agentShare = пул всегда; вне диапазонов — отказ (INV-2).../domain/agency-commission-policy.md — AgencyRetentionKind, INV-2../api/agency/create-agency-policy.md; UC-RWD-005
US-OWN-AG-02Как владелец агентства, я хочу задавать персональные условия удержания для отдельных агентов поверх правила по умолчанию, чтобы гибко мотивировать сильных сотрудников.ShouldAgentOverrides содержит уникальные AgentUserId (каждый — активный пользователь агентства, сверка при активации, INV-3); оверрайд применяется по AgentUserId независимо от текущего членства агента.../domain/agency-commission-policy.md — AgentOverrides, INV-3../api/agency/create-agency-policy.md, ../api/agency/update-agency-policy.md
US-OWN-AG-03Как владелец агентства, я хочу активировать новую политику так, чтобы предыдущая автоматически архивировалась, чтобы всегда была ровно одна действующая политика.MustActivate атомарно переводит прежнюю активную политику в Archived (INV-1); в Active документ правил иммутабелен — правка через новый Draft + Activate (INV-4).../domain/agency-commission-policy.md — INV-1/4, статусы../api/agency/activate-agency-policy.md, ../api/agency/archive-agency-policy.md, ../api/agency/list-agency-policies.md
US-OWN-AG-04Как владелец агентства, я хочу понимать поведение при отсутствии активной политики, чтобы не терять деньги агентов по недосмотру.ShouldБез активной политики в момент подтверждения начисления удержание агентства = 0, весь пул достаётся агенту (fallback INV-6); строка Platform применяется независимо.../domain/agency-commission-policy.md — INV-6../domain/commission-accrual.md — распределение при Confirm
US-OWN-AG-05Как владелец агентства, я хочу завести временную мотивационную кампанию agent-boost (повышенная доля набора агентов на период), чтобы стимулировать продажи, не трогая базовую политику.ShouldКампания — отдельный агрегат с периодом и набором агентов; BoostRule выражает долю агента (AgentPercentOfPool/AgentPercentOfPrice, INV-8); при подтверждении начисления активный на CompletedAt boost перекрывает базовое правило.../domain/agency-commission-policy.md — AgentBoostCampaignEntity, INV-8../api/agency/create-agent-boost-campaign.md, ../api/agency/activate-agent-boost-campaign.md
US-OWN-AG-06Как владелец агентства, я хочу управлять жизненным циклом boost-кампаний (активировать/досрочно завершить/архивировать) и видеть их реестр, чтобы контролировать мотивационные акции.CouldDraft → Active → Archived; в Active меняется только EffectiveTo (INV-10); периоды boost одного агента не пересекаются (INV-9) — резолюция детерминирована.../domain/agency-commission-policy.md — INV-9/10../api/agency/activate-agent-boost-campaign.md, ../api/agency/archive-agent-boost-campaign.md, ../api/agency/list-agent-boost-campaigns.md
US-OWN-AG-07Как владелец агентства, я хочу перераспределить доли конкретной сделки (пул Agency ↔ Agent) с обязательной причиной, чтобы точечно исправлять частные договорённости.ShouldPer-deal корректировка меняет только пул между Agency и Agent (строка Platform и gross неизменны, INV-11), пока строка Agent не включена в поручение; оставляет append-only аудит-строку; при MoneyReceived дельта компенсируется проводкой кошелька.../domain/commission-accrual.md — INV-11, Distribution../api/agency/adjust-accrual-distribution.md; UC-RWD-011

Роль: Владелец агентства — выплаты, сводки и выгрузки (US-OWN-AG-08..15)​

Выплаты собираются из долей агентов, у которых деньги от застройщика уже получены (гейт MoneyReceived). Excel-выгрузки дают бухгалтерскую и управленческую картину; исполнение платежей — вне платформы (ручная отметка).

№User StoryПриоритетКритерий приёмкиПокрытие: доменПокрытие: API / отчёт / UC / события
US-OWN-AG-08Как руководитель агентства, я хочу одобрить заявку агента на изменение его доли или отклонить её с комментарием, чтобы решения по пулу принимал именно руководитель.ShouldАгент лишь предлагает сумму своей доли; одобрение из Pending исполняет Distribution-корректировку (Agent = ProposedAgentAmount, Agency = пул − ProposedAgentAmount) под теми же guard-ами; на начисление — не более одной открытой заявки (INV-12).../domain/commission-accrual.md — CommissionAdjustmentRequestEntity, INV-12../api/agency/approve-distribution-adjustment.md; UC-RWD-011
US-OWN-AG-09Как руководитель агентства, я хочу сформировать платёжное поручение по свободным долям агентов за период, чтобы выплатить вознаграждения.MustПоручение Kind = AgencyCommission собирает свободные Agent-строки начислений в MoneyReceived (гейт пройден), группирует по агентам в позиции; занятые строки в другое поручение не попадают (INV-1).../domain/payout-order.md — INV-1/2, AgencyCommission../api/agency/create-payout-order.md, ../api/agency/update-payout-order-items.md; UC-RWD-005
US-OWN-AG-10Как руководитель агентства, я хочу утвердить поручение (заморозив состав) и передать его в бухгалтерию, чтобы зафиксировать сумму к выплате.MustApprove из Draft при ItemsCount ≥ 1 замораживает состав, статус PendingPayment («ожидается»); повторные переходы отклоняются guard-ом статуса.../domain/payout-order.md — INV-6, статусы../api/agency/approve-payout-order.md
US-OWN-AG-11Как руководитель/бухгалтер агентства, я хочу отметить поручение выплаченным (исполнение вне платформы), чтобы каскадно закрыть доли агентов и провести дебет кошельков.MustMarkPaid из PendingPayment проставляет PaidAt поручению/позициям/строкам; начисление, у которого все Agent-строки выплачены, переходит MoneyReceived → Paid (INV-7); дебет счетов AgentCommission — по событию (ADR-0065).../domain/payout-order.md — INV-7../api/agency/mark-payout-order-paid.md; ../events/payout-order-status-changed.md
US-OWN-AG-12Как руководитель агентства, я хочу отклонить или отменить поручение с освобождением его строк, чтобы вернуть доли в оборот при ошибке состава.ShouldReject (с обязательной причиной) из PendingPayment и Cancel из Draft возвращают строкам PayoutOrderItemId = null (INV-8) — они снова доступны следующему поручению.../domain/payout-order.md — INV-8, статусы../api/agency/reject-payout-order.md, ../api/agency/cancel-payout-order.md, ../api/agency/list-payout-orders.md
US-OWN-AG-13Как владелец агентства, я хочу видеть онлайн-сводку комиссий агентства и по каждому агенту (получим / получили × подтверждено / ожидает / деньги получены), чтобы контролировать финансы без выгрузки.ShouldСводка раскладывает суммы по стадиям начислений в границах tenant-а; доступ — rewards.commission.view-all; отменённые начисления в денежные суммы не входят.../domain/commission-accrual.md — статусы, строки распределения../api/agency/get-agency-commission-summary.md, ../api/agency/get-agent-commission-summary.md, ../api/agency/list-agency-accruals.md
US-OWN-AG-14Как владелец агентства, я хочу выгрузить детальную Excel-таблицу (строка = комиссионное начисление по сотруднику и сделке) с полной раскладкой (gross, удержание ПИН, пул, доля агента, удержание агентства) за период, чтобы сверять с бухгалтерией и разбирать спорные сделки.ShouldАсинхронная задача формирует XLSX по tenant-у за период (фильтры агент/статус); скачивание — по signed URL; период ≤ 1 года, ≤ 2 активных задач; PII инвесторов в файл не попадает; денежные totals исключают Cancelled.../domain/commission-accrual.md — строки распределения, FinalPriceAmount../reports/agency-rewards-by-employee-per-deal.md; ../api/agency/create-rewards-export.md, ../api/agency/get-rewards-export-job.md; UC-RWD-012
US-OWN-AG-15Как владелец агентства, я хочу выгрузить сводную Excel-таблицу за период (строка = агент: число сделок, начислено, доля агента, удержано, разбивка по стадиям), чтобы считать зарплатные итоги и оценивать эффективность.ShouldСводная XLSX-задача агрегирует по AgentUserId за период; строка раскладывает долю агента по стадиям (подтверждено / получено / выплачено) + ожидает подтверждения; итоговая строка по агентству; те же лимиты и signed URL.../domain/commission-accrual.md — статусы, строки Agent/Agency../reports/agency-rewards-period-summary.md; ../api/agency/create-rewards-export.md; UC-RWD-012

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

USОграничениеПринято
US-OWN-AG-01/07Политика и корректировки делят только пул, не grossУдержание ПИН (строка Platform) снимается до политики и неприкосновенно для агентства (ADR-0066)
US-OWN-AG-03/05Правка политики/boost не пересчитывает подтверждённые начисленияСнапшот применённого правила (AppliedPolicyId/AppliedBoostCampaignId) фиксируется в начислении (ADR-0068 п.4)
US-OWN-AG-09/11Выплата только после гейта денегИсточник строк — доли агентов из начислений в MoneyReceived (ADR-0067)
US-OWN-AG-11Исполнение платежей отложеноПолная структура поручений + ручной MarkPaid (решение №9 ТЗ); банковские реквизиты не хранятся
US-OWN-AG-14/15Выгрузки — SensitiveAsync pipeline + signed URL (TTL 1 час), audit ExportSensitive, retention файла 7 дней (ADR-0041); PII инвесторов не выгружается

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

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

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