ksv741
2d14081d27
Use owner enums for error and T-Bank protocol values with ESLint regression checks. Preserve open wire fallbacks and keep protocol imports independent of DI and Prisma. Verified npm ci, verify, 226 unit tests, 262 isolated e2e tests and unchanged OpenAPI.
5.8 KiB
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.
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. Логика, DTO definitions и HTTP routes
в эти файлы не помещаются. Type exports обозначаются export type.
Преобразование provider records происходит на boundary: например,
tbank-portfolio.mapper.ts и bond-money.mapper.ts; protobuf decimal helper
остаётся отдельным чистым входом integration. tbank-protocol.ts и
tbank-error-code.ts также импортируются напрямую: их enums и guards
не должны загружать DI/Prisma через service exports. 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.
Retry, cache и protocol
Existing client уже владеет bounded FIFO queue, rate limit, deadline и retry классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop в service. Не отключай TLS verification ради окружения: используй документированный CA mechanism. Точные параметры и ограничения принадлежат validated environment и TbankClient.
Эта 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 — пример controlled upstream responses. Проверь queue/deadline/retry limit, token translation, cache isolation и late response для затронутых ветвей. Fixtures синтетические; реальная сеть, секреты и пользовательские accounts не нужны. Logging использует existing logger.