docs: reorganize system knowledge by domain
This commit is contained in:
@@ -0,0 +1,100 @@
|
||||
# Брокерские счета
|
||||
|
||||
На странице `/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).
|
||||
|
||||
Согласованное поведение описывает [спецификация счетов](../../../specs/openspec/specs/brokerage-accounts/spec.md).
|
||||
Её раздел об экране пока требует одноколоночного списка и не описывает
|
||||
счётчики акций и облигаций. Текущая реализация и её проверки используют
|
||||
две колонки на широком экране и показывают эти счётчики. Расхождение требует
|
||||
отдельного согласования требований; в этой документации отражён наблюдаемый экран.
|
||||
Reference in New Issue
Block a user