docs: reorganize system knowledge by domain
This commit is contained in:
@@ -0,0 +1,149 @@
|
||||
# Интеграция с T-Bank Invest
|
||||
|
||||
T-Bank — источник доступных пользователю инвестиционных счетов, текущих
|
||||
позиций и денег, исполненных операций и рыночных сведений об инструментах.
|
||||
WealthLedger обращается к Invest API на сервере по gRPC over TLS и преобразует
|
||||
ответы в собственный HTTP API. Изображения логотипов загружаются браузером
|
||||
отдельно из публичного CDN; это не доступ к личным брокерским данным.
|
||||
|
||||
## Данные и ответственность
|
||||
|
||||
| Категория | Для чего используется |
|
||||
| --- | --- |
|
||||
| Открытые счета | Определить доступный состав счетов и проверить доступ к конкретному счёту |
|
||||
| Портфель и денежные остатки | Показать текущий состав инвестиций и итоги по исходным валютам |
|
||||
| Исполненные операции | Построить журнал и выделить полученные купоны и дивиденды |
|
||||
| Инструменты и рынок | Имена, идентификаторы, цены, свечи, параметры акций и облигаций |
|
||||
| Купоны и дивиденды | Построить будущие события по текущим позициям и календарь инструмента |
|
||||
|
||||
T-Bank определяет исходные данные и права token. Backend проверяет локальную
|
||||
сессию, выбирает подключение её пользователя и устанавливает доступ к счёту.
|
||||
Наличие идентификатора счёта в URL этого доступа не подтверждает.
|
||||
|
||||
[MOEX](moex.md) и [НКР](nkr.md) дополняют публичные сведения об облигациях; они не заменяют
|
||||
брокера как источник личных позиций и исполненных выплат. Границы источников
|
||||
показаны в [контексте](../architecture/context.md), смысл дополнений — в
|
||||
[описании облигаций](../domains/instruments/bonds.md).
|
||||
|
||||
## Публичные логотипы
|
||||
|
||||
T-Bank Brands CDN — отдельная публичная граница для изображений.
|
||||
Backend передаёт имя файла `logoName` из метаданных инструмента; frontend
|
||||
строит URL на `invest-brands.cdn-tinkoff.ru` и загружает изображение браузером.
|
||||
Эти запросы не используют HTTP-клиент приложения, его Bearer token
|
||||
или token Invest API. Лимитер и повторы серверных gRPC-вызовов к ним не относятся.
|
||||
|
||||
Логотипы используются в портфеле, операциях, будущих событиях, поиске и
|
||||
страницах инструментов. Отсутствующее имя или ошибка изображения оставляют
|
||||
буквенную заглушку и не меняют финансовые значения. Правило построения URL
|
||||
принадлежит [форматированию frontend](../../frontend/src/shared/lib/display.ts).
|
||||
|
||||
## Проверка и сохранение подключения
|
||||
|
||||
Авторизованный пользователь управляет одним подключением в настройках.
|
||||
Интерфейс просит read-only T-Bank Invest token: он вводится в поле пароля
|
||||
и отправляется backend. API возвращает только состояние подключения и время
|
||||
его сохранения, не token. Успешное сохранение очищает поле, ошибка оставляет
|
||||
введённое значение для исправления. Удаление требует подтверждения в форме;
|
||||
во время изменения действия секции заблокированы.
|
||||
|
||||
Схема показывает динамический сценарий создания или замены подключения.
|
||||
SQLite — локальное хранилище backend, а не отдельный сетевой участник.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as Пользователь
|
||||
participant F as React SPA
|
||||
participant B as Backend API
|
||||
participant T as T-Bank Invest API
|
||||
participant D as Локальная SQLite
|
||||
U->>F: Вводит token и сохраняет подключение
|
||||
F->>B: PUT connection с Bearer и token
|
||||
B->>T: GetAccounts OPEN по gRPC over TLS
|
||||
alt Проверка успешна, в том числе при пустом списке счетов
|
||||
T-->>B: Доступные открытые счета
|
||||
B->>D: Создать или заменить шифротекст AES-256-GCM
|
||||
B-->>F: Подключено и время сохранения
|
||||
F->>F: Обновить статус и сбросить финансовые выборки
|
||||
F-->>U: Показать подтверждённое подключение
|
||||
else Token отклонён или источник недоступен
|
||||
T-->>B: Ошибка проверки
|
||||
B-->>F: INVALID_TBANK_TOKEN или TBANK_UNAVAILABLE
|
||||
F-->>U: Локальная ошибка, прежнее подключение сохранено
|
||||
end
|
||||
```
|
||||
|
||||
Перед проверкой backend удаляет внешние пробелы token и отклоняет пустое
|
||||
значение. Успешный пустой список счетов подтверждает token: наличие позиций
|
||||
не является условием подключения. Ошибка проверки не заменяет уже сохранённое
|
||||
подключение. Сетевой вызов T-Bank и запись SQLite выполняются последовательно,
|
||||
но не образуют общую транзакцию между системами.
|
||||
|
||||
## Состояние и ошибки
|
||||
|
||||
Состояние без подключения содержит `connected: false` и `connectedAt: null`.
|
||||
После создания или замены `connectedAt` содержит время успешного сохранения
|
||||
в RFC 3339 UTC. Это время подключения, а не отметка свежести портфеля.
|
||||
Чтение статуса показывает сохранённое состояние; оно не выполняет заново
|
||||
проверку token у брокера. Если статус загрузить не удалось, интерфейс
|
||||
показывает ошибку с повтором, а не форму с предполагаемым отсутствием
|
||||
подключения.
|
||||
|
||||
`INVALID_TBANK_TOKEN` означает отказ внешней аутентификации или прав доступа.
|
||||
`TBANK_UNAVAILABLE` сообщает о временной или иной upstream-ошибке, включая
|
||||
исчерпание очереди. Ответы и ошибки не содержат token. Удаление подключения
|
||||
идемпотентно: удаляется локальный секрет и прекращается его использование
|
||||
для последующих запросов. Оно не описывает отзыв token на стороне T-Bank.
|
||||
|
||||
Согласованное поведение сохранено в workspace-спецификации
|
||||
[T-Bank connection](../../specs/openspec/specs/tbank-connection/spec.md).
|
||||
Точные endpoints и формы ответов определяет backend OpenAPI;
|
||||
[HTTP API](../architecture/http-api.md) описывает общую границу.
|
||||
|
||||
## Граница финансового кэша
|
||||
|
||||
Успешное создание, замена или удаление подключения меняет границу повторного
|
||||
использования финансовых данных. Это относится и к сохранению того же самого
|
||||
token: предыдущее подключение не становится источником данных нового.
|
||||
Неуспешная операция сохраняет прежнее подключение и его доступные данные.
|
||||
Механизм generation, поздние ответы и сброс клиентских выборок объясняет
|
||||
[свежесть данных](../architecture/cross-cutting/data-freshness.md#смена-подключения).
|
||||
|
||||
## Конфигурация и ограничения
|
||||
|
||||
Backend хранит token в шифротексте AES-256-GCM с новым nonce при каждом
|
||||
сохранении. Ключ находится только в серверном окружении. Расшифровка нужна
|
||||
серверной интеграции; ни шифротекст, ни token не входят в публичное API.
|
||||
Причины границы и шифрования сохранены в
|
||||
[ADR 003](../adr/003-tbank-server-side-grpc-boundary.md) и
|
||||
[ADR 004](../adr/004-encrypted-per-user-tbank-token.md).
|
||||
|
||||
| Настройка | Значение и смысл |
|
||||
| --- | --- |
|
||||
| `TOKEN_ENCRYPTION_KEY` | Обязательный ключ AES-256-GCM: 32 байта, закодированные в base64 |
|
||||
| `TBANK_GRPC_ENDPOINT` | Адрес gRPC; по умолчанию `invest-public-api.tbank.ru:443` |
|
||||
| `TBANK_RATE_LIMIT_PER_SECOND` | Число стартующих T-Bank RPC в секунду на экземпляр backend; по умолчанию `5` |
|
||||
| `TBANK_CA_CERT_PATH` | Необязательный путь к доверенному корневому CA в PEM для сетей с TLS-инспекцией; проверка TLS сохраняется |
|
||||
|
||||
Параметры окружения определяет backend
|
||||
[validateEnv](../../backend/src/config/env.validation.ts) (workspace-ссылка).
|
||||
Общий FIFO-лимитер ограничивает поток RPC и отклоняет новый вызов при 50
|
||||
ожидающих. Для `UNAVAILABLE`, `DEADLINE_EXCEEDED` и `RESOURCE_EXHAUSTED`
|
||||
предусмотрен один повтор через секунду. Deadline каждой попытки — 15 секунд,
|
||||
а ожидание места в лимитере не является временем этой сетевой попытки.
|
||||
Параметры попыток принадлежат
|
||||
[T-Bank client](../../backend/src/tbank/tbank.client.ts) (workspace-ссылка);
|
||||
решение об ограниченных повторах — [ADR 005](../adr/005-tbank-upstream-resilience.md).
|
||||
|
||||
Большое число ранее неизвестных инструментов требует отдельных запросов
|
||||
metadata. При перегруженной очереди необязательные имена могут быть заменены
|
||||
идентификаторами; это не доказывает потерю самой позиции. Изменение локального
|
||||
лимита требует учёта разрешённой квоты T-Bank: оно не увеличивает квоту
|
||||
поставщика. Диагностика соединения описана в
|
||||
[локальном окружении](../development/local-workspace.md).
|
||||
|
||||
Ключ шифрования не ротируется автоматически. Лимитер и кэши принадлежат
|
||||
одному экземпляру; изменения подключения не координируются между
|
||||
распределёнными экземплярами backend. Интеграция использует сохранённый
|
||||
protobuf-контракт T-Bank: обновление внешнего протокола и проверка
|
||||
совместимости требуют отдельного изменения интеграции.
|
||||
Reference in New Issue
Block a user