GET /api/v1/my/wallet/transactions — История транзакций моего кошелька

Назначение

Отдаёт пользователю постраничную историю движений по его счетам кошелька: начисления по сделкам (CommissionCredit), реферальные начисления (ReferralCredit), выплаты (PayoutDebit), корректировки (Adjustment/Correction). Пользователь видит, из чего сложился текущий баланс каждого счёта и когда прошла каждая операция.

Metadata

Поле	Значение
Сервис/контекст	wallet
API area	user
Feature group	my-wallet
Статус	draft
Документ	docs/06-services/wallet/api/user/list-my-wallet-transactions.md

Актор и доступ

Проверка	Значение
Actor type	User (агент / партнёр / любой пользователь-холдер)
Auth policy / Permissions	wallet.transactions.view-own
Scope (RBAC)	платформа (личные данные пользователя)
Record-level	только проводки по счетам с HolderUserId = текущий пользователь

HTTP-контракт

Поле	Значение
Method	GET
Route	/api/v1/my/wallet/transactions
Success status	200
Correlation	сквозной trace через заголовок traceparent

Входные данные / параметры запроса

Поле	Источник	Тип	Обязательность	Валидация / Ограничения
UserId	identity claims	Guid	Да	текущий пользователь — record-level граница выборки
AccountKind	query	string? (enum WalletAccountKind)	Нет	AgentCommission / ReferralCommission; не указан — по всем счетам пользователя
OperationKind	query	string? (enum WalletOperationKind)	Нет	фильтр по виду операции (../../domain/ledger-transaction.md)
From	query	DateTimeOffset?	Нет	фильтр по OccurredAt >= From
To	query	DateTimeOffset?	Нет	фильтр по OccurredAt < To; при обоих границах From < To
Page / PageSize	query	int	Нет	paging — ../README.md

Модель ответа

Страница WalletTransactionModel (дом модели и paging-конверт — ../README.md). Сортировка — OccurredAt по убыванию (новые сверху); внутри одинакового момента — по TransactionId (стабильный порядок страниц). Каждая строка несёт AccountKind — при выборке без фильтра истории двух счетов различимы.

Алгоритм

1. Определить счета пользователя (HolderUserId = текущий); при заданном AccountKind — только счёт этого вида. Счетов нет → 200 с пустой страницей.
2. Проверить фильтры: AccountKind/OperationKind вне enum / From >= To / paging вне диапазонов → ValidationError.
3. Выбрать проводки этих счетов из журнала по фильтру периода, спроецировать в WalletTransactionModel (Amount — со знаком относительно счёта, BalanceAfter — зафиксированный при проведении), вернуть страницу. Журнал append-only — история не меняется задним числом; корректировки видны отдельными строками Correction/Adjustment, а не правкой прежних.

Ошибки и failure modes

Только общие ошибки области (../README.md): ValidationError (400), UNAUTHORIZED (401), FORBIDDEN (403).

Совместимость и наблюдаемость

• Новые значения WalletOperationKind — additive: клиент показывает неизвестный вид операции как «прочее», не падая.
• Logs: запрос без сумм (UserId, фильтры, размер страницы); metrics: латентность p95; traces — traceparent.

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

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

• API (3): GET /api/v1/my/wallet — Мой кошелёк (балансы счетов), GET /api/v1/platform/wallet/accounts/{accountId}/ledger — Журнал проводок счёта, Wallet API — реестр операций и общие контрактные модели
• Use Cases (1): UC-WLT-004. Холдер смотрит баланс и историю операций
• registries (1): Реестр API-методов PIN
• index.md (1): Wallet Service

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

• Журнал: ../../domain/ledger-transaction.md; счета: ../../domain/wallet-account.md; общие модели: ../README.md.
• Балансы: get-my-wallet.md.