ksv741
d698ed9425
Keep financial ownership, atomic publication and refresh CAS. Failed refresh leaves cookies untouched; logout still clears them. Remove full-history candle prefetch and special metadata retries. Use native Pino request context instead of parallel middleware. BREAKING CHANGE: remove investment stateVersion, queued sync state, and tbank-sync status progress/resources. Consumers must observe resources through sync=observe with the updated frontend contract.
6.2 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.
Все RPC, включая metadata, допускают один повтор временной upstream-ошибки.
Переполнение локальной очереди не повторяется. Свечи загружаются по требуемому
диапазону; prefetch портфеля и автоматический переход к all не поддерживаются.
Эта 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.