docs/features/brokerage-accounts.md

Брокерские счета

Авторизованный пользователь просматривает открытые поддерживаемые инвестиционные счета T-Bank, доступные через его текущее T-Bank connection, на странице /accounts. Для получения списка требуется сохранённое T-Bank connection; frontend никогда не обращается к T-Bank напрямую. WealthLedger не хранит Brokerage Account как долговременное владение отдельно от брокерского подключения.

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: Открывает /accounts
  F->>B: GET /api/v1/brokerage-accounts (Bearer)
  B->>D: Читает T-Bank connection
  alt Connection отсутствует
    B-->>F: 409 TBANK_NOT_CONNECTED
    F-->>U: Переход к настройкам T-Bank
  else Connection существует
    B->>T: GetAccounts(OPEN) over TLS
    T-->>B: Счета или ошибка
    par Для каждого поддерживаемого счета
      B->>T: GetPortfolio + GetPositions over TLS
      T-->>B: Исходные валютные значения или temporary unavailable
    end
    B-->>F: Нормализованный массив с локальными summary либо Problem Details
    F-->>U: Карточки счетов или error-state
  end

API

GET /api/v1/brokerage-accounts требует Bearer access token и возвращает массив:

[
  {
    "id": "account-id",
    "name": "Основной",
    "type": "BROKERAGE",
    "openedOn": "2024-08-13",
    "portfolioSummary": {
      "totalsByCurrency": [
        { "currency": "RUB", "value": "12500.50" },
        { "currency": "USD", "value": "40" }
      ]
    }
  }
]

Поддерживаемые type: BROKERAGE, INDIVIDUAL_INVESTMENT, INVEST_BOX, MONEY_MARKET_FUND. Банковские и неизвестные типы T-Bank не возвращаются. Пустое upstream-название заменяется названием типа, а отсутствующая дата открытия передаётся как null.

portfolioSummary — nullable наблюдение текущего портфеля конкретного счета. totalsByCurrency точно складывает ненулевые текущие стоимости позиций и денежные остатки только в одинаковой исходной ISO-валюте; FX-конвертация и единый итог не выполняются. Успешный пустой портфель возвращает пустой массив. Когда T-Bank временно недоступен только для summary одного счета, этот счет всё равно остаётся в списке с portfolioSummary: null; переход к его деталям и остальные карточки не блокируются.

Список является результатом текущего наблюдения T-Bank connection: если счёт больше не открыт, не поддерживается или недоступен через это подключение, он не считается доступным для WealthLedger. Ошибки connection или token, а также ошибки исходного получения списка, не превращаются в частичный ответ.

Состояния

При первом запросе /accounts frontend показывает structural skeleton заголовка и карточек, а не отдельный spinner; placeholder не содержит данных и не участвует в keyboard focus. После успешного ответа либо ошибки используются обычные нижеописанные состояния.

• 409 TBANK_NOT_CONNECTED: список не запрашивается у T-Bank, экран ведёт в настройки.
• 400 INVALID_TBANK_TOKEN: сохранённый token не удаляется, экран ведёт в настройки для замены или удаления.
• 503 TBANK_UNAVAILABLE: экран предлагает повторить загрузку или открыть настройки.
• Неизвестная ошибка: экран предлагает только повторить загрузку.
• Успешный пустой ответ: штатное состояние отсутствия инвестиционных счетов.

Карточка ведёт на /accounts/:accountId по всей области и сохраняет нативную клавиатурную навигацию/focus. Она показывает название, локализованный тип, до двух итогов в исходных валютах, число остальных валют, дату открытия без времени и видимое действие открытия. Недоступная или пустая summary отображается локально на карточке.

Ограничения MVP

Список запрашивается при открытии экрана без ручного обновления и без refetch при возврате фокуса. Frontend использует успешный React Query-кэш в течение 60 секунд, поэтому повторный вход в этот интервал не выполняет новый GET. Когда уже показанный список обновляется в фоне, он остаётся на экране: индикатор обновления и ошибка с повторной попыткой отображаются рядом с последним успешным ответом, включая пустой список. Это Client Cached Snapshot, а не server-side fallback. Backend не хранит кэш и не передаёт метку свежести. Балансы, доходность, графики, портфель, закрытые счета и операции не входят в feature.