GET /api/v1/platform/wallet/accounts — Реестр счетов кошелька
Назначение
Отдаёт оператору ПИН постраничный реестр всех счетов кошелька — холдерских (AgentCommission /
ReferralCommission / AgencyCommission) и системных (PlatformSettlement / PlatformRevenue) — с
текущими балансами. Рабочий инструмент финансового контроля: поиск счёта холдера перед корректировкой
(create-wallet-adjustment.md), просмотр системных остатков, разбор
инцидентов рассинхрона (ADR-0021).
Metadata
| Поле | Значение |
|---|---|
| Сервис/контекст | wallet |
| API area | platform |
| Feature group | platform-wallet |
| Статус | draft |
| Документ | docs/06-services/wallet/api/platform/list-wallet-accounts.md |
Актор и доступ
| Проверка | Значение |
|---|---|
| Actor type | Operator(Admin) (оператор ПИН) |
| Auth policy / Permissions | wallet.accounts.view-all |
| Scope (RBAC) | платформа |
| Audit | read-sensitive: обращения к реестру логируются (актор, фильтры — без сумм) |
HTTP-контракт
| Поле | Значение |
|---|---|
| Method | GET |
| Route | /api/v1/platform/wallet/accounts |
| Success status | 200 |
| Correlation | сквозной trace через заголовок traceparent |
Входные данные / параметры запроса
| Поле | Источник | Тип | Обязательность | Валидация / Ограничения |
|---|---|---|---|---|
HolderUserId | query | Guid? | Нет | фильтр по пользователю-холдеру |
HolderCompanyId | query | Guid? | Нет | фильтр по компании-холдеру; взаимоисключим с HolderUserId (оба заданы → ValidationError) |
Kind | query | string? (enum WalletAccountKind) | Нет | AgentCommission / ReferralCommission / AgencyCommission / PlatformSettlement / PlatformRevenue |
Page / PageSize | query | int | Нет | paging — ../README.md |
Модель ответа WalletAccountModel (страница)
Расширение WalletBalanceModel (../README.md) полями холдера и служебными атрибутами —
только для platform-area.
| Поле | Тип | Обязательность | Источник | Описание |
|---|---|---|---|---|
AccountId | Guid | Да | WalletAccountEntity.Id | Идентификатор счёта. |
AccountKind | string (enum WalletAccountKind) | Да | AccountKind | Вид счёта. |
HolderUserId | Guid? | Нет (null у системных и компанейских) | HolderUserId | Пользователь-холдер. |
HolderCompanyId | Guid? | Нет (null у системных и пользовательских) | HolderCompanyId | Компания-холдер. |
HolderDisplayName | string? | Нет | display-реплика (user-display-replica.md) | Подпись холдера: DisplayName по HolderUserId (холдерский пользовательский счёт) либо CompanyName по HolderCompanyId (счёт агентства). null у системных счетов и пока холдер не реплицирован (клиент показывает id). Резолв из локальной реплики, без синхронного identity. |
Balance | decimal | Да | Balance | Текущий баланс (scale 2); системные счета могут быть отрицательными. |
CurrencyId | short | Да | CurrencyId | Валюта счёта (handbook/domain/snapshots.md); RUB-only. |
CreatedAt | DateTimeOffset | Да | CreatedAt | Момент lazy-создания счёта (первая кредитующая проводка). |
LastTransactionAt | DateTimeOffset? | Нет | журнал | Момент последней проводки счёта. |
Сортировка — CreatedAt по убыванию; при заданном холдере — по AccountKind.
Алгоритм
Тривиальное чтение реестра: проверить permission и фильтры (HolderUserId/HolderCompanyId
взаимоисключимы, Kind из enum — иначе ValidationError), выбрать счета по фильтрам, подтянуть подписи
холдеров из display-реплики (DisplayName/CompanyName, без синхронного identity), спроецировать в
WalletAccountModel, вернуть страницу. Холдерские счета появляются в реестре lazy — после первой
кредитующей проводки; системные — при первом обращении проводок. Отсутствие строки реплики →
HolderDisplayName = null, не ошибка.
Ошибки и failure modes
Только общие ошибки области (../README.md): ValidationError (400), UNAUTHORIZED
(401), FORBIDDEN (403).
Совместимость и наблюдаемость
- Новые значения
AccountKindи optional-поля модели — additive. - Logs: актор + фильтры без сумм; metrics: латентность p95, частота обращений (
wallet_platform_registry_reads_total); traces —traceparent.
Обратные ссылки
Автоссылки: где используется этот документ.
- Домен (CQRS) (1): Entity (Replica): UserDisplayReplicaEntity
- API (4): GET /api/v1/platform/wallet/accounts/{accountId}/ledger — Журнал проводок счёта, POST /api/v1/platform/wallet/adjustments — Ручная корректировка счёта, POST /api/v1/platform/wallet/statement-exports — Постановка выписки по любому счёту (XLSX), Wallet API — реестр операций и общие контрактные модели
- Use Cases (3): UC-WLT-003. ПИН-админ вручную корректирует баланс, UC-WLT-004. Холдер смотрит баланс и историю операций, UC-WLT-005. Оператор ПИН смотрит журнал проводок счёта (сверка)
- Консюмеры (1): Consumer: Wallet Identity Display Sync (wallet-identity-users)
- registries (1): Реестр API-методов PIN
- index.md (1): Wallet Service
Связанные документы
- Сущность: ../../domain/wallet-account.md; журнал: ../../domain/ledger-transaction.md; подписи холдеров: ../../domain/user-display-replica.md.
- Корректировка счёта: create-wallet-adjustment.md.
- Общие модели и ошибки: ../README.md; ADR-0021 — разбор рассинхронов.