docs: simplify conventions layout

2026-09-15 05:58:33 +03:00
parent 9810d47e42
commit 016782657a
13 changed files with 263 additions and 276 deletions
@@ -0,0 +1,72 @@
+# Backend integrations
+
+## Выбор boundary
+
+T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient; NCR ratings —
+NcrRatingsClient. Сервисы 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](../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](../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#конфигурация-и-ограничения).
+
+Эта queue/retry policy относится к T-Bank. MOEX/NCR HTTP clients используют
+собственный bounded timeout и безопасный unavailable outcome; не приписывай им
+gRPC retry policy. При изменении upstream сначала прочитай конкретный client.
+
+При 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](../architecture.md#logging).