# Backend integrations

## Выбор boundary

T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient. Сервисы use case
используют объявленные клиентом records; SDK clients, metadata и transport errors
остаются внутри integration. Frontend не вызывает
T-Bank и не получает credentials/proto client. Reference source —
[ADR 003](../../../docs/adr/003-tbank-server-side-grpc-boundary.md) и
[connection behavior](../../../docs/integrations/tbank.md).

`modules/investments/tbank-connection` — пользовательская capability чтения,
создания/замены и удаления подключения. `integrations/tbank` — технические
RPC, credentials/access и resilience. Эти владельцы не объединяются из-за имени
поставщика; низкоуровневый client не зависит от пользовательского module.

`*.client.ts` содержит transport и его retries; `*.api.ts` только перечисляет
публичные exports. Все шесть `auth/operations/portfolio/tbank/moex/ncr.api.ts`
имеют одинаковую роль программной границы, определённую в
[Architecture](backend-architecture.md). Логика, DTO definitions и HTTP routes
в эти файлы не помещаются. Type exports обозначаются `export type`.

Преобразование provider records происходит на boundary: например,
`tbank-portfolio.mapper.ts` и `bond-money.mapper.ts`; protobuf decimal helper
остаётся отдельным чистым входом integration. Domain получает внутренние
значения и не импортирует gRPC/SDK types. Не добавляй новый adapter на каждый
client или mapper для простого копирования полей. Даты/units/nano разбираются
на границе клиента/его mapping, а не становятся моделью чистых расчётов.

Для нового account use case сначала используй TbankAccessService: access,
connection generation и invalid-token translation не дублируются в callers.
Mapper внешних финансовых значений остаётся внутри business capability,
обычно в infrastructure по [Architecture](backend-architecture.md).

## Retry, cache и protocol

Existing client уже владеет bounded FIFO queue, rate limit, deadline и retry
классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop
в service. Не отключай TLS verification ради окружения: используй документированный
CA mechanism. Точные параметры и ограничения принадлежат
[connection configuration](../../../docs/integrations/tbank.md#конфигурация-и-ограничения).

При query/cache change установи key, user/account/generation ownership,
freshness и поведение late response. Старый результат не может обслужить новую
connection generation. Client Cached Snapshot frontend отличается от backend
cache/stale policy; semantics конкретного use case читай через
[feature index](../../../docs/README.md#предметные-области).

Внешний auth failure и временная недоступность имеют разные public codes;
raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService
и общем HTTP boundary. Для HTTP error change читай HTTP API/Security по trigger.

Vendor proto хранится в `src/integrations/tbank/proto/contracts`; для обновления сверяй
официальный source и влияние на loader/DTO, не редактируй read-only references.
Generated artifacts, если есть, создавай из source, без ручной подгонки вывода.

## Безопасный путь и проверка

Сначала добавь нужный operation в существующий client и используй его из
ответственного service. Отдельный abstraction/adapter оправдан новой
ответственностью или несовместимым protocol, не только вторым методом.

[TbankClient tests](../../src/integrations/tbank/tbank.client.spec.ts) — пример controlled
upstream responses. Проверь queue/deadline/retry limit, token translation,
cache isolation и late response для затронутых ветвей. Fixtures синтетические;
реальная сеть, секреты и пользовательские accounts не нужны.
Logging использует [existing logger](backend-architecture.md#logging).