docs/features/brokerage-account-ledger.md

Журнал операций брокерского счёта

Авторизованный пользователь просматривает исполненные операции одного доступного брокерского счёта на /accounts/:accountId/operations. На обзоре /accounts/:accountId отображаются пять последних событий и ссылка на полный журнал. Ошибка или пустой результат этого блока не заменяет Portfolio.

sequenceDiagram
  participant U as User
  participant F as Frontend
  participant B as Backend
  participant D as SQLite
  participant T as T-Bank gRPC
  U->>F: Открывает журнал счёта
  F->>B: GET /api/v1/brokerage-accounts/:accountId/operations
  B->>D: Читает T-Bank connection
  B->>T: GetAccounts(OPEN)
  B->>T: GetOperationsByCursor(EXECUTED)
  B-->>F: Страница Account Ledger
  F-->>U: Операции, фильтры и навигация

API

GET /api/v1/brokerage-accounts/:accountId/operations требует Bearer access token. Необязательные from и to задают включительный период; без периода запрос начинается с 1 января текущего года. categories принимает trade, income, tax, fee, transfer, other; cursor и limit управляют cursor-пагинацией.

Необязательный instrumentUid фильтрует историю одной бумаги через upstream и включает историю с открытия доступных счетов, если from не задан. Для сделок quantity содержит исполненное quantityDone; если его нет, значение null. Дата остаётся датой операции. Подробности и ограничения — страница акции.

Ответ передаёт accountId, items, nextCursor, hasNext и observedAt. Каждая Ledger Entry соответствует ровно одной операции T-Bank и содержит её тип, категорию, описание, дату, доступный инструмент, nullable logoName, payment, quantity, price, accruedInterest и commission. logoName — presentation metadata: если она недоступна, это не меняет запись журнала.

Деньги передаются decimal strings в исходной ISO-валюте. Frontend только форматирует значения. Комиссия сделки остаётся деталью той же записи; операции без payment отображаются как «Без движения денег».

Поведение и ограничения

При первом открытии полного журнала frontend показывает structural skeleton ожидаемых filters и rows вместо отдельного spinner. После появления response filters и данные сохраняют существующую семантику; уже показанный контент не заменяется skeleton во время pending action или фонового обновления.

• Запрашиваются только исполненные операции T-Bank.
• Полный журнал фильтруется по периоду (два DateInput «С»/«По» с форматом DD.MM.YYYY и min/max-ограничением, русская локаль календаря) и категориям (MultiSelect с мультивыбором из trade, income, tax, fee, transfer, other). Фильтры имеют черновик в контролах и применённое состояние: изменение черновика не вызывает новый запрос к серверу; «Применить» коммитит черновик и сбрасывает cursor-пагинацию на первую страницу; «Сбросить» очищает черновик и немедленно применяет пустой фильтр (период по умолчанию и все категории). Cursor-пагинация («Назад»/«Далее») работает по последнему применённому фильтру, не по черновику.
• В полном журнале и пяти последних записях обзора одна и та же компактная строка показывает логотип инструмента либо буквенный fallback, описание операции, дату, инструмент и денежное движение. Денежная метка строки показывает подпись конкретного типа события: для income-записи — «Купон» или «Дивиденд» (по upstream-типу купона или дивиденда), для остальных — подпись категории («Сделка», «Налог», «Комиссия», «Перевод», «Прочее»). Подпись типа выводится один раз и не повторяется во вторичной метадате (дата · инструмент); направление передаётся знаком «+» / «−` и семантическим цветом, а не текстом. Записи без движения денег остаются нейтральными («Без движения денег»).
• Полный журнал не показывает цену, количество, НКД и комиссию записи. Страница акции переиспользует тот же LedgerEntryRow с дополнительными количеством, ценой и ссылкой на счёт. Даты имеют формат ДД.ММ.ГГГГ, время операций явно обозначено UTC. При отсутствии описания используется локализованный тип операции.
• Backend хранит в памяти процесса до 100 страниц Account Ledger: свежая страница живёт до 30 секунд, а при переполнении вытесняется давно не использовавшаяся страница (LRU). Ключ включает непрозрачную generation текущего T-Bank connection, пользователя, счёт, нормализованные период и categories, cursor и limit; отсутствующий to приводится к текущему 30-секундному bucket. Проверка connection и доступа к счёту выполняется до выдачи кэшированной страницы. После успешного создания, замены или удаления connection сохранённая либо поздно завершившаяся страница предыдущей generation недоступна Operations, Income Summary и Income Analytics. Старые страницы удаляются обычными TTL/LRU limits; операции не сохраняются и не синхронизируются локально.
• Журнал не рассчитывает остаток после операции, суммарные доходы или налоги, историческую стоимость Portfolio, конвертацию валют и рыночные изменения цены.
• 409 TBANK_NOT_CONNECTED, 400 INVALID_TBANK_TOKEN, 404 недоступного счёта и 503 TBANK_UNAVAILABLE используют существующую семантику ошибок T-Bank.