GET /api/v1/my/wallet — Мой кошелёк (балансы счетов)
Назначение
Отдаёт пользователю балансы всех его счетов кошелька: AgentCommission (агентские комиссии по
сделкам) и ReferralCommission (реферальные вознаграждения) — раздельно, без смешения
(ADR-0065). Агент видит,
сколько ему причитается и ещё не выплачено по сделкам; партнёр — сколько накоплено по реферальной
программе; один пользователь может иметь оба баланса одновременно.
Metadata
| Поле | Значение |
|---|---|
| Сервис/контекст | wallet |
| API area | user |
| Feature group | my-wallet |
| Статус | draft |
| Документ | docs/06-services/wallet/api/user/get-my-wallet.md |
Актор и доступ
| Проверка | Значение |
|---|---|
| Actor type | User (агент / партнёр / любой пользователь-холдер) |
| Auth policy / Permissions | wallet.balance.view-own |
| Scope (RBAC) | платформа (личные данные пользователя) |
| Record-level | только счета с HolderUserId = текущий пользователь |
HTTP-контракт
| Поле | Значение |
|---|---|
| Method | GET |
| Route | /api/v1/my/wallet |
| Success status | 200 |
| Correlation | сквозной trace через заголовок traceparent |
Входные данные / параметры запроса
| Поле | Источник | Тип | Обязательность | Валидация / Ограничения |
|---|---|---|---|---|
UserId | identity claims | Guid | Да | текущий пользователь — единственный критерий выборки |
Модель ответа MyWalletModel
| Поле | Тип | Обязательность | Источник | Описание |
|---|---|---|---|---|
HolderDisplayName | string? | Нет | display-реплика (DisplayName по UserId) | ФИО холдера для подписи ЛК; резолв из локальной реплики, без синхронного identity (user-display-replica.md). null — реплика ещё не наполнена (клиент подставляет имя из своего профиля/JWT). |
Accounts | IReadOnlyList<WalletBalanceModel> | Да (может быть пуст) | счета пользователя | Балансы по видам счетов; дом модели — ../README.md. |
Возвращаются только пользовательские виды счетов (AgentCommission, ReferralCommission) —
не более одного счёта каждого вида (уникальность «холдер + вид»,
../../domain/wallet-account.md). Счета создаются lazy при первой
кредитующей проводке: пустой список / отсутствие вида означает нулевой баланс — клиент показывает 0.
Алгоритм
Тривиальное чтение: выбрать счета с HolderUserId = текущий пользователь, спроецировать в
WalletBalanceModel и подтянуть HolderDisplayName из display-реплики (без синхронного identity;
отсутствие строки → null). Отдаётся хранимый баланс (быстрые чтения ЛК); он периодически сверяется с
пересчётом из журнала — расхождение является инцидентом рассинхрона (ADR-0021), а не поводом отдать
иное значение. Свежесть — по общему правилу eventual-consistency (../README.md).
Ошибки и failure modes
Только общие ошибки области (../README.md): UNAUTHORIZED (401), FORBIDDEN (403 —
нет permission). Отсутствие счетов ошибкой не является — 200 с пустым списком.
Совместимость и наблюдаемость
- Новые optional-поля модели ответа и новые значения
AccountKind— additive; клиент игнорирует неизвестные виды счетов. - Logs: запрос без сумм (
UserId, число счетов); metrics: латентность p95; traces —traceparent.
Обратные ссылки
Автоссылки: где используется этот документ.
- Домен (CQRS) (1): Entity (Replica): UserDisplayReplicaEntity
- API (2): GET /api/v1/my/wallet/transactions — История транзакций моего кошелька, Wallet API — реестр операций и общие контрактные модели
- Use Cases (1): UC-WLT-004. Холдер смотрит баланс и историю операций
- Консюмеры (1): Consumer: Wallet Identity Display Sync (wallet-identity-users)
- registries (1): Реестр API-методов PIN
- index.md (1): Wallet Service
Связанные документы
- Сущность: ../../domain/wallet-account.md; реестр и общие модели: ../README.md; подпись холдера: ../../domain/user-display-replica.md.
- История транзакций счетов: list-my-wallet-transactions.md.
- Источники движения денег: ../../consumers/rewards-commission-money-received.md, ../../consumers/rewards-referral-accrual-status-changed.md, ../../consumers/rewards-payout-order-status-changed.md.