docs/domains/accounts/overview.md

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

На странице `/accounts` пользователь выбирает открытый поддерживаемый
инвестиционный счёт T-Bank и переходит к его портфелю. Для этого нужны
действующая сессия и сохранённое
[подключение T-Bank](../../integrations/tbank.md). Frontend обращается
только к backend. Счёт не хранится как долговременное локальное владение
независимо от брокерского подключения.

```mermaid
sequenceDiagram
  participant U as Пользователь
  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
  alt Подключение отсутствует
    B-->>F: 409 TBANK_NOT_CONNECTED
    F-->>U: Переход к настройкам T-Bank
  else Подключение сохранено
    B->>T: GetAccounts(OPEN) over TLS
    T-->>B: Счета или ошибка
    par Для каждого поддерживаемого счета
      B->>T: GetPortfolio + GetPositions over TLS
      T-->>B: Позиции и деньги либо временная ошибка
    end
    B-->>F: Счета со сводками либо ошибка
    F-->>U: Карточки счетов или объяснение ошибки
  end
```

## Счёт и его сводка

Брокерский счёт принадлежит системе брокера. WealthLedger получает его
идентификатор, имя, тип и доступную дату открытия через текущее подключение;
локальная сессия пользователя сама по себе не подтверждает доступ к счёту.
Закрытый, неподдерживаемый или недоступный через подключение счёт не входит
в текущий список. Порядок списка сохраняет порядок источника.

Поддерживаются брокерский счёт (`BROKERAGE`), ИИС (`INDIVIDUAL_INVESTMENT`),
Инвесткопилка (`INVEST_BOX`) и фонд денежного рынка (`MONEY_MARKET_FUND`).
Банковские и неизвестные типы исключаются. Имя очищается от внешних пробелов;
пустое имя заменяется названием типа. Отсутствующая дата открытия остаётся
неизвестной, а известная передаётся календарной датой без времени.

`GET /api/v1/brokerage-accounts` требует Bearer token и возвращает список
с необязательной финансовой сводкой каждого счёта. Точная форма ответа
принадлежит [HTTP API](../../architecture/http-api.md).

| Состояние `portfolioSummary` | Что оно означает |
| --- | --- |
| Доступные валютные итоги | Текущие стоимости позиций и деньги сложены точно в исходной валюте |
| Доступная сводка с пустыми итогами | Портфель получен, но валютных итогов нет; это не ошибка загрузки |
| `null` | Финансовая сводка этого счёта временно недоступна; метаданные и переход на счёт сохраняются |

Валюты не конвертируются и не объединяются в общую сумму. Деньги уже входят
в валютный итог; они не образуют второй самостоятельный итог. Правила
неизвестных стоимостей совпадают со [справочником портфеля](../portfolio/data-reference.md).

Сводка также сообщает число ненулевых обычных позиций акций и облигаций
(`stockPositionCount`, `bondPositionCount`). Это количество наименований,
а не сумма штук или лотов. Подсчёт использует уже полученные позиции,
не требует метаданных и включает дробные и короткие позиции, даже если их
стоимость неизвестна. Нулевые, виртуальные и иные типы позиций в эти два
счётчика не входят. Пустой портфель даёт нулевые счётчики; недоступная
сводка не подменяется нулями.

Временная недоступность сводки одного счёта остаётся локальной для него.
Ошибка подключения, отклонение токена или невозможность получить исходный
список не превращаются в частичный успешный список.

## Состояния

При первом запросе `/accounts` frontend показывает каркас заголовка
и карточек; декоративные элементы не содержат данных и не получают
клавиатурный фокус. После успешного ответа либо ошибки используются
обычные нижеописанные состояния.

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

Карточка ведёт на `/accounts/:accountId` по всей области и доступна с клавиатуры. На широком экране карточки расположены в две колонки, на узком — в одну. Карточка показывает название, локализованный тип, крупный валютный итог и вторую валюту при наличии, число остальных валют, дату открытия без времени и видимое действие открытия. Отдельные цветные блоки «Акции» и «Облигации» показывают количество наименований бумаг. Недоступная или пустая сводка отображается локально; отсутствие сумм не скрывает известные количества бумаг, а недоступная сводка не подменяет их нулями. Наведение и видимый клавиатурный фокус подчёркивают переход; настройка уменьшения движения отключает анимацию.

## Свежесть и границы

Список запрашивается при открытии экрана без ручного обновления и без обновления при возврате фокуса. Frontend использует успешный кэш TanStack Query в течение 60 секунд, поэтому повторный вход в этот интервал не выполняет новый GET. Когда уже показанный список обновляется в фоне, он остаётся на экране: индикатор обновления и ошибка с повторной попыткой отображаются рядом с последним успешным ответом, включая пустой список. Это клиентский сохранённый ответ; серверный запасной список не выдаётся. Backend не хранит кэш и не передаёт метку свежести. Список не заменяет полный [портфель](../portfolio/overview.md),
[журнал операций](../operations/overview.md) или историю закрытых счетов.
Для совокупного результата доступен [режим «Все счета»](../portfolio/all-accounts.md).

Согласованное поведение описывает [спецификация счетов](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-accounts/spec.md).
Её раздел об экране пока требует одноколоночного списка и не описывает
счётчики акций и облигаций. Текущая реализация и её проверки используют
две колонки на широком экране и показывают эти счётчики. Расхождение требует
отдельного согласования требований; в этой документации отражён наблюдаемый экран.