docs/features/tbank-connection.md

Подключение T-Bank

Авторизованный пользователь управляет одним подключением к T-Bank Invest в настройках. Токен вводится только в поле пароля, отправляется в backend для проверки и больше не отображается.

sequenceDiagram
  participant F as Frontend
  participant B as Backend
  participant T as T-Bank gRPC
  participant D as SQLite
  F->>B: PUT /api/v1/tbank-connection (Bearer, token)
  B->>T: GetAccounts(OPEN) over TLS
  T-->>B: счета или ошибка проверки
  B->>D: сохранить шифротекст AES-256-GCM
  B-->>F: { connected, connectedAt }

API

• GET /api/v1/tbank-connection возвращает { connected: false, connectedAt: null } или статус подключенного аккаунта.
• PUT /api/v1/tbank-connection принимает { token }, проверяет его через GetAccounts и создает или заменяет подключение.
• DELETE /api/v1/tbank-connection идемпотентен и возвращает 204.
• connectedAt - метка времени RFC 3339 в UTC. Ответы и ошибки API никогда не содержат токен.

INVALID_TBANK_TOKEN означает, что T-Bank отклонил аутентификацию или права доступа. TBANK_UNAVAILABLE означает временную ошибку, превышение лимита, ожидание в очереди или другую ошибку внешнего сервиса.

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

• TOKEN_ENCRYPTION_KEY - закодированный в base64 32-байтный ключ AES-256-GCM; обязателен при запуске.
• TBANK_GRPC_ENDPOINT по умолчанию имеет значение invest-public-api.tbank.ru:443.
• TBANK_RATE_LIMIT_PER_SECOND задаёт максимальное число T-Bank RPC в секунду на экземпляр backend; значение по умолчанию -- 5.
• TBANK_CA_CERT_PATH - необязательный путь к корневому CA-сертификату PEM для сетей с TLS-инспекцией; проверка TLS остается включенной.

FIFO-ограничитель на экземпляр запускает не более 5 запросов в секунду и принимает не более 50 ожидающих вызовов. Для UNAVAILABLE, DEADLINE_EXCEEDED и RESOURCE_EXHAUSTED выполняется одна повторная попытка через секунду. Deadline каждой попытки - 15 секунд.

Портфель с большим числом ранее не кэшированных инструментов создаёт отдельные metadata lookup. Если в такой ситуации очередь переполняется и позиции получают FIGI вместо names, увеличьте TBANK_RATE_LIMIT_PER_SECOND в соответствии с разрешённой upstream-квотой; для локального портфеля из множества позиций использовалось значение 50.

Ограничения

Подключение используется поставленными сценариями Brokerage Accounts, Portfolio, Account Ledger и Future Cash Events; frontend не обращается к T-Bank напрямую. Token encryption key не ротируется, rate limit остаётся per-instance, а обновление connection не сериализуется между распределёнными экземплярами backend. Вендорные protobuf-контракты взяты из references/moex-vibe; при необходимости обновляйте их вручную по официальной документации T-Bank Invest API.