consolidate-tbank-connection-resolution — Design

Context

Backend T-Bank flows сейчас повторяют один knowledge cluster: чтение сохранённой T-Bank connection по User, расшифровку token, запрос открытых accounts, отсечение неподдерживаемых account types, проверку accountId для account-scoped flows и перевод INVALID_TBANK_TOKEN в публичную ошибку API. Полная account-scoped последовательность есть в Portfolio, Account Ledger и Future Cash Events; список Brokerage Accounts использует тот же persisted connection и supported-account rules без проверки конкретного accountId; T-Bank connection flow отдельно валидирует candidate token и использует то же crypto/error knowledge.

Поставленное поведение менять нельзя. Для account-scoped read flows отсутствие connection остаётся 409 TBANK_NOT_CONNECTED, invalid token остаётся 400 INVALID_TBANK_TOKEN, недоступный или неподдерживаемый account остаётся 404, а upstream availability errors сохраняют текущие 503/throw-through semantics. Account Ledger уже документирует, что connection и account access проверяются до выдачи cached page; этот порядок должен сохраниться.

Ограничения backend: NestJS module/provider model, Node 22, public HTTP API /api/v1, generated OpenAPI как frontend contract authority, canonical gate npm ci && npm run verify.

Goals / Non-Goals

Goals:

Сконцентрировать persisted T-Bank connection lookup, token decrypt, supported-account policy, account access check и invalid-token translation в одном backend module.
Сохранить public API behavior, DTO shape, routes, status codes и Problem Details codes.
Сохранить service-specific responsibilities: Portfolio normalizes portfolio data and snapshot fallback, Account Ledger maps operations and pagination, Future Cash Events calculates projected events, Brokerage Accounts maps the account list.
Сделать новый module осмысленной test surface для shared access behavior, сократив дублирование tests в feature services до orchestration и feature-specific behavior.

Non-Goals:

Новые T-Bank account types или изменение supported-account semantics.
Frontend changes, OpenAPI snapshot changes, generated client updates или runtime contract changes.
Изменения Portfolio snapshot cache, Account Ledger page cache, Upcoming Events dividend/instrument caches или metadata cache semantics.
Durable storage, token versioning, account history или cache invalidation after token replacement.
Замена T-Bank gRPC client или добавление другой integration library.

Decisions

D1. Ввести один T-Bank access module с двумя public use cases. Module предоставляет list-oriented use case для supported Brokerage Accounts и account-scoped use case для flows, которым нужен доступ к конкретному Brokerage Account. Module владеет persisted connection lookup, token decrypt, getOpenAccounts, supported-account filtering и inaccessible-account decision. Feature services получают resolved token/account context или supported account list и не повторяют access sequence.

Alternative: извлечь только маленький supportedAccounts constant и crypto helper. Отклонено: access ordering и error translation остаются размазанными по services, поэтому future account policy changes всё ещё могут разойтись.

D2. Оборачивать account-scoped flow execution для централизованного invalid-token translation. Простой resolveAccount(userId, accountId) -> { token, account } не покрывает invalid-token errors, которые могут быть выброшены более поздними T-Bank calls в том же service flow. Поэтому account-scoped use case выполняет feature handler внутри translation boundary access module. Missing connection, account lookup и handler failures используют одно правило translation для INVALID_TBANK_TOKEN; unrelated exceptions сохраняют существующее propagation.

Alternative: оставить try/catch INVALID_TBANK_TOKEN в каждом feature service после shared resolver. Отклонено: это уменьшает duplication, но оставляет behavior-critical string comparison в нескольких call sites.

D3. Оставить T-Bank connection management вне account access, разделяя только crypto/error primitives. Сохранение или удаление T-Bank connection валидирует candidate token и не разрешает persisted account. Этот flow не должен принудительно проходить через account-scoped access use case. Shared module может предоставить или переиспользовать crypto provider и invalid-token translator, но connection management сохраняет текущую ответственность за token validation, encryption и Portfolio snapshot invalidation.

D4. Единая supported-account policy. Supported upstream account types и их normalized Investment Account Type/fallback display name живут в одной policy, которой владеет T-Bank access module. Account list use case и account-scoped validation оба опираются на эту policy, поэтому добавление или удаление supported account type становится one-policy change.

D5. Сохранить Account Ledger cache ordering. Account Ledger должен по-прежнему проверять current connection и account access до обращения к LRU page cache. Implementation order: сначала access module, затем page cache, затем upstream operations call при cache miss. Это сохраняет documented behavior и 30-секундный token-replacement nuance, уже отражённый в as-built docs.

D6. Tests переезжают к shared interface плюс тонкое service coverage. Новые tests покрывают observable branches access module: missing connection, invalid token during account resolution, inaccessible/unsupported account, supported account filtering и invalid token из wrapped account-scoped handler. Существующие service tests корректируются так, чтобы проверять service-specific behavior и факт использования shared access module без повторного тестирования одной access matrix в каждом service.

Delivery Map

Area	Status	Architectural outcome or N/A reason
frontend	`N/A`	Frontend behavior, generated client и OpenAPI snapshot не меняются.
backend	`affected`	T-Bank access module централизует connection lookup, token decrypt, supported-account policy, account access check и invalid-token translation; feature services сохраняют только feature-specific data retrieval, mapping и cache behavior.
specs	`affected`	Этот SDD change хранит Proposal, skipped Delta Specs, Design и Tasks для behavior-preserving refactor.
docs	`N/A`	As-built product behavior намеренно не меняется; docs обновляются только если implementation обнаружит ещё не задокументированный behavior nuance.

Contract Gate Decision

Gate	Status	Reason
runtime-openapi	`N/A`	Public API contract, DTO shape и generated frontend snapshot не меняются.

Solution Assessment

Формальная build-versus-buy assessment не triggered. Change не добавляет и не заменяет auth, storage, external integration, observability, caching, concurrency control или infrastructure. Он сохраняет существующий T-Bank gRPC client и переносит project-owned access policy за более глубокий in-process module.

Risks / Trade-offs

Behavior drift during refactor. Refactor затрагивает shared access behavior нескольких endpoints. Mitigation: сохранить existing public status codes/codes, добавить shared access tests для common matrix и оставить feature-service tests для endpoint-specific behavior.
Over-wide callback interface. Wrapping feature handlers централизует invalid-token translation, но может создать впечатление, что access module отвечает за feature logic. Mitigation: handler context ограничен resolved token/account data; normalization, pagination, projections и caches остаются в feature services.
Account Ledger cache ordering regression. Перенос access code может случайно начать отдавать cached pages до проверки current connection/account access. Mitigation: Design требует access-before-cache ordering, а Tasks должны включить focused regression test или semantic verification для этого behavior.
T-Bank connection management partial duplication. Connection settings flow не может использовать account-scoped resolution, потому что валидирует candidate token. Mitigation: разделить crypto/error primitives, но сохранить connection management отдельно, не искажая account access interface.

Migration Plan

Поставка выполняется одной backend-focused последовательностью без runtime migration:

Добавить shared T-Bank access module и tests для common access matrix.
Перенести supported-account policy в shared module.
Refactor account-scoped flows так, чтобы они выполнялись через shared access module, сохраняя feature-specific mapping, cache и fallback behavior каждого flow.
Refactor Brokerage Accounts list на использование shared supported-account policy/use case.
Оставить T-Bank connection management behavior неизменным, разделив только безопасные crypto/error primitives, если это полезно.
Запустить backend canonical gate, semantic verification против этого Design и Proposal, затем workspace change verification перед archive.

Rollback — обычный code revert: schema, data, contract или cache migration не вводятся.

11 KiB Raw Permalink Blame History Unescape Escape