docs(ai): add scoped backend conventions

2026-09-09 16:23:03 +03:00
parent 320e8a04b0
commit a83e26e5ef
10 changed files with 377 additions and 36 deletions
@@ -0,0 +1,47 @@
+# 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).