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

UC-WLT-004. Холдер смотрит баланс и историю операций

Назначение​

Описывает сценарий просмотра кошелька: агент видит раздельные балансы «агентские комиссии» и «реферальные комиссии» и историю операций по каждому счёту («сколько мне причитается и ещё не выплачено»); партнёр — накопления по реферальной программе; руководитель агентства — балансы своих агентов; оператор ПИН — все счета платформы. Связан с контекстом wallet.

Metadata​

ПолеЗначение
IDUC-WLT-004
Контекстwallet (см. docs/06-services/wallet/)
Типосновной
Статусdraft

Актор​

ПолеЗначение
РольАгент / Партнёр (основной поток); Руководитель агентства / Администратор платформы (альтернативные)
Permissions / scopewallet.balance.view-own + wallet.transactions.view-own (холдер); wallet.team.view (руководитель, scope = организация); wallet.accounts.view-all (ПИН, платформенный scope)
Tenantвне tenant-модели: счета пользователей user-centric (баланс агента переживает смену агентства, ADR-0061 п.5)
Record-levelхолдер видит только счета, где он — HolderUserId; руководитель — счёт своей компании и AgentCommission-счета агентов текущего состава (ростер — по display-реплике холдеров)

Предусловие​

  • Пользователь авторизован и имеет соответствующий permission.
  • По холдеру существуют счета (созданы lazy при первом кредите); если кредитов ещё не было — кошелёк показывает нулевое состояние без счетов (не ошибка).

Триггер​

ПолеЗначение
ИсточникUI
Триггерящий элементраздел «Кошелёк» в ЛК (агент/партнёр); раздел вознаграждений агентства; admin-реестр счетов

Основной Поток​

  1. Холдер открывает «Кошелёк» в ЛК.
  2. Интерфейс запрашивает балансы (get-my-wallet.md, GET /api/v1/my/wallet); система отдаёт счета холдера раздельно по видам (wallet-account.md): AgentCommission и ReferralCommission — отдельные суммы, без смешения.
  3. Холдер видит по каждому счёту: вид, баланс (Balance), валюту.
  4. Холдер открывает историю счёта; интерфейс запрашивает страницу операций (list-my-wallet-transactions.md, GET /api/v1/my/wallet/transactions) с фильтрами: вид счёта, вид операции (WalletOperationKind), период; сортировка — по моменту проведения (новые сверху), пагинация.
  5. Система отдаёт проводки счёта из журнала (ledger-transaction.md): вид операции, направление (зачисление/списание), сумма, баланс после операции (BalanceAfter), момент бизнес-факта.
  6. Холдер сопоставляет операции с ЛК-статусами вознаграждений: кредит появился после подтверждения получения денег, списание — после выплаты поручения.

Альтернативные Потоки​

A1. Руководитель агентства (wallet.team.view)​

  1. Руководитель открывает балансы вознаграждений команды.
  2. Система отдаёт (list-agency-agent-balances.md): счёт AgencyCommission своей компании и балансы AgentCommission-счетов агентов текущего состава (ростер — по локальной display-реплике холдеров user-display-replica.md, без синхронного identity на read-path; лаг реплики — устаревший ростер, косметика). Подписи (ФИО агентов, название агентства) — из той же реплики. Балансы user-centric: руководитель видит весь остаток счёта агента, включая накопленное в прежних агентствах; разрез «сколько должно именно наше агентство» — свободные Agent-строки распределений в rewards.
  3. Реферальные балансы агентов (ReferralCommission) и истории их счетов руководителю не отдаются — партнёрская программа персональна; детализация «за что начислено» — в rewards по своим permissions.

A2. Оператор/админ ПИН (wallet.accounts.view-all)​

  1. Оператор открывает admin-реестр счетов (list-wallet-accounts.md): все счета с фильтрами по виду и холдеру, включая системные PlatformSettlement (транзит; баланс <= 0, интерпретация знака — wallet-account.md, INV-WLT-3) и PlatformRevenue (доход ПИН).
  2. По счёту доступен полный журнал транзакций, включая причины Adjustment/Correction.

A3. Кошелёк ещё пуст​

  1. У холдера не было ни одного кредита — счета не создавались (lazy).
  2. Система отдаёт пустой список счетов; интерфейс показывает нулевые балансы и подсказку «начисления появятся после подтверждения получения денег по вашим сделкам».

Постусловие​

  • Состояние системы не изменено (чтение).
  • Показанные балансы согласованы с журналом: Balance = Σ кредитов − Σ дебетов проводок счёта; последняя операция истории несёт BalanceAfter, равный текущему балансу.

Возможные Ошибки​

КодHTTPУсловиеПоведение клиента
WALLET_ACCOUNT_NOT_FOUND404Запрошена история счёта, не принадлежащего актору / несуществующего (record-level fail closed)Вернуться к списку своих счетов

Acceptance Criteria​

#КритерийПроверка
AC1Given агент с кредитами по сделкам и по рефералке, When он открывает кошелёк, Then он видит два раздельных баланса (AgentCommission, ReferralCommission), суммы не смешаныUI/интеграционный тест
AC2Given история счёта, When холдер листает страницы, Then каждая операция показывает вид, направление, сумму и BalanceAfter; последняя операция сходится с текущим балансоминтеграционный тест
AC3Given холдер, When он запрашивает историю чужого счёта, Then отказ 404 (record-level, fail closed)негативный тест
AC4Given агент сменил агентство, When он открывает кошелёк, Then его балансы и история сохранены (user-centric счета)тест смены агентства (ADR-0061 п.5)
AC5Given руководитель агентства, When он открывает балансы команды, Then видны счёт агентства и AgentCommission-балансы агентов текущего состава; ReferralCommission-балансы и агенты чужих агентств не виднытест A1
AC6Given холдер без единого кредита, When он открывает кошелёк, Then показано нулевое состояние без ошибкитест A3

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

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

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