docs/integrations/tbank.md

Интеграция с T-Bank Invest

T-Bank — источник доступных пользователю инвестиционных счетов, текущих позиций и денег, исполненных операций и рыночных сведений об инструментах. WealthLedger обращается к Invest API на сервере по gRPC over TLS и преобразует ответы в собственный HTTP API. Изображения логотипов загружаются браузером отдельно из публичного CDN; это не доступ к личным брокерским данным.

Данные и ответственность

Категория	Для чего используется
Открытые счета	Определить доступный состав счетов и проверить доступ к конкретному счёту
Портфель и денежные остатки	Показать текущий состав инвестиций и итоги по исходным валютам
Исполненные операции	Построить журнал и выделить полученные купоны и дивиденды
Инструменты и рынок	Имена, идентификаторы, цены, свечи, параметры акций и облигаций
Купоны и дивиденды	Построить будущие события по текущим позициям и календарь инструмента

T-Bank определяет исходные данные и права token. Backend проверяет локальную сессию, выбирает подключение её пользователя и устанавливает доступ к счёту. Наличие идентификатора счёта в URL этого доступа не подтверждает.

MOEX и НКР дополняют публичные сведения об облигациях; они не заменяют брокера как источник личных позиций и исполненных выплат. Границы источников показаны в контексте, смысл дополнений — в описании облигаций.

Публичные логотипы

T-Bank Brands CDN — отдельная публичная граница для изображений. Backend передаёт имя файла logoName из метаданных инструмента; frontend строит URL на invest-brands.cdn-tinkoff.ru и загружает изображение браузером. Эти запросы не используют HTTP-клиент приложения, его Bearer token или token Invest API. Лимитер и повторы серверных gRPC-вызовов к ним не относятся.

Логотипы используются в портфеле, операциях, будущих событиях, поиске и страницах инструментов. Отсутствующее имя или ошибка изображения оставляют буквенную заглушку и не меняют финансовые значения. Правило построения URL принадлежит форматированию frontend.

Проверка и сохранение подключения

Авторизованный пользователь управляет одним подключением в настройках. Интерфейс просит read-only T-Bank Invest token: он вводится в поле пароля и отправляется backend. API возвращает только состояние подключения и время его сохранения, не token. Успешное сохранение очищает поле, ошибка оставляет введённое значение для исправления. Удаление требует подтверждения в форме; во время изменения действия секции заблокированы.

Схема показывает динамический сценарий создания или замены подключения. SQLite — локальное хранилище backend, а не отдельный сетевой участник.

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: Атомарно сохранить token, новую revision и membership
    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. Удаление подключения идемпотентно: удаляются локальный секрет, личные datasets и work; поздняя публикация прежней revision запрещена. Общие неперсональные источники могут сохраняться. Оно не описывает отзыв token на стороне T-Bank.

Согласованное поведение сохранено в workspace-спецификации T-Bank connection. Точные endpoints и формы ответов определяет backend OpenAPI; HTTP API описывает общую границу.

Граница финансового кэша

Успешное создание, замена или удаление подключения меняет границу повторного использования финансовых данных. Это относится и к сохранению того же самого token: предыдущее подключение не становится источником данных нового. Неуспешная операция сохраняет прежнее подключение и его доступные данные. Механизм внутренней revision, поздние ответы и сброс клиентских выборок объясняет свежесть данных.

Конфигурация и ограничения

Backend хранит token в шифротексте AES-256-GCM с новым nonce при каждом сохранении. Ключ находится только в серверном окружении. Расшифровка нужна серверной интеграции; ни шифротекст, ни token не входят в публичное API. Причины границы и шифрования сохранены в ADR 003 и ADR 004.

Настройка	Значение и смысл
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 (справочный источник). Общий FIFO-лимитер ограничивает поток RPC и не допускает более 50 ожидающих. Для UNAVAILABLE, DEADLINE_EXCEEDED и RESOURCE_EXHAUSTED обычный RPC допускает один повтор через секунду. Deadline каждой попытки — 15 секунд, а ожидание места в лимитере не является временем этой сетевой попытки. Для поиска метаданных GetInstrumentBy разрешены две повторные попытки с паузами 2 и 4 секунды после неудачных попыток. Они применяются к тем же временным кодам и к переполнению локальной очереди; перед каждой попыткой проверяется её вместимость. Постоянные ошибки и отказ авторизации не повторяются. Подтверждённый NOT_FOUND при поиске метаданных означает отсутствие инструмента, а не временный сбой. Остальные RPC при полной очереди завершаются сразу. Параметры попыток принадлежат T-Bank client (справочный источник); решение об ограниченных повторах — ADR 005.

Большое число ранее неизвестных инструментов требует отдельных запросов metadata. При перегруженной очереди необязательные имена могут быть заменены идентификаторами; это не доказывает потерю самой позиции. Изменение локального лимита требует учёта разрешённой квоты T-Bank: оно не увеличивает квоту поставщика.

Ключ шифрования не ротируется автоматически. Новый ключ не расшифрует прежнее подключение: нужен исходный ключ либо повторный ввод собственного token через настройки. Правила резервного копирования учитывают отдельное хранение ключа. Лимитер и кэши принадлежат одному экземпляру; изменения подключения не координируются между распределёнными экземплярами backend. Интеграция использует сохранённый protobuf-контракт T-Bank: обновление внешнего протокола и проверка совместимости требуют отдельного изменения интеграции.