48 lines
3.3 KiB
Markdown
48 lines
3.3 KiB
Markdown
# Backend integrations
|
|
|
|
## Выбор boundary
|
|
|
|
T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient. Сервисы use case
|
|
получают нормализованный результат через эти clients. Frontend не вызывает
|
|
T-Bank и не получает credentials/proto client. Reference source —
|
|
[ADR 003](../../../docs/adr/003-tbank-server-side-grpc-boundary.md) и
|
|
[connection behavior](../../../docs/features/tbank-connection.md).
|
|
|
|
Для нового account use case сначала используй TbankAccessService: access,
|
|
connection generation и invalid-token translation не дублируются в callers.
|
|
Чистый mapper финансового значения остаётся рядом с domain owner.
|
|
|
|
## Retry, cache и protocol
|
|
|
|
Existing client уже владеет bounded FIFO queue, rate limit, deadline и retry
|
|
классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop
|
|
в service. Не отключай TLS verification ради окружения: используй документированный
|
|
CA mechanism. Точные параметры и ограничения принадлежат
|
|
[connection configuration](../../../docs/features/tbank-connection.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/AI_INDEX.md#features).
|
|
|
|
Внешний auth failure и временная недоступность имеют разные public codes;
|
|
raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService
|
|
и общем HTTP boundary. Для HTTP error change читай HTTP API/Security по trigger.
|
|
|
|
Vendor proto хранится в `src/tbank/proto/contracts`; для обновления сверяй
|
|
официальный source и влияние на loader/DTO, не редактируй read-only references.
|
|
Generated artifacts, если есть, создавай из source, без ручной подгонки вывода.
|
|
|
|
## Безопасный путь и проверка
|
|
|
|
Сначала добавь нужный operation в существующий client и используй его из
|
|
ответственного service. Отдельный abstraction/adapter оправдан новой
|
|
ответственностью или несовместимым protocol, не только вторым методом.
|
|
|
|
[TbankClient tests](../../src/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).
|