ksv741
32c12fb10d
Backend security / security (pull_request) Successful in 7s
Backend verify / verify (pull_request) Successful in 2m28s
Conventional commits / commits (pull_request) Successful in 25s
Backend security / security (push) Successful in 6s
Backend verify / verify (push) Successful in 2m16s
74 lines
5.6 KiB
Markdown
74 lines
5.6 KiB
Markdown
# Backend integrations
|
|
|
|
## Выбор boundary
|
|
|
|
T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient; NCR ratings —
|
|
NcrRatingsClient. Сервисы use case
|
|
используют объявленные клиентом records; SDK clients, metadata и transport errors
|
|
остаются внутри integration. Credentials и proto client не входят в публичный
|
|
HTTP API. Connection lifecycle проверяется на границе соответствующего module
|
|
и [Security](security-auth.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. Точные параметры и ограничения принадлежат
|
|
[validated environment](../../src/config/env.validation.ts) и
|
|
[TbankClient](../../src/integrations/tbank/tbank.client.ts).
|
|
|
|
Эта 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. Успешная замена/deletion подключения меняет generation
|
|
даже при сохранении прежнего token; ошибка оставляет прежнее подключение.
|
|
Кэш конкретного use case принадлежит его service и tests. Не переноси
|
|
сохранённый snapshot между пользователями или поколениями подключения.
|
|
|
|
Внешний 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).
|