118 lines
8.0 KiB
Markdown
118 lines
8.0 KiB
Markdown
# Backend Architecture Refactor
|
||
|
||
Дата: 2026-06-25
|
||
Статус: draft
|
||
|
||
## Контекст
|
||
|
||
После аудита backend-архитектуры от 2026-06-25 и последующей фичи
|
||
`backend-architecture-improvements` большая часть первого слоя долга закрыта: общий envelope DTO,
|
||
domain exceptions, dependency-aware health checks, DI-подключение middleware и разделение
|
||
`MoexClientService`.
|
||
|
||
Оставшийся долг неоднороден. Часть пунктов требует новых продуктовых или доменных решений
|
||
(`T-Bank` multi-tenancy, локальный read-path истории операций, device sessions, ledger-модель). Эти
|
||
изменения не должны попадать в локальный рефакторинг без отдельной спецификации, потому что меняют
|
||
поведение, модель данных или threat model.
|
||
|
||
Текущая фича фиксирует только refactor-only итерацию: привести существующий backend к более
|
||
правильным архитектурным границам без добавления новых пользовательских возможностей и без изменения
|
||
публичной формы API, кроме уточнения валидации некорректных входных данных.
|
||
|
||
## Цель
|
||
|
||
Снизить backend technical debt в существующем поведении за счёт точечных архитектурных правок:
|
||
безопаснее обрабатывать ошибки, формализовать production-конфигурацию, усилить DTO-валидацию,
|
||
сузить `any` на границе T-Bank gRPC, улучшить cache metadata и синхронизировать опубликованную
|
||
backend-документацию с текущим кодом.
|
||
|
||
## Требования
|
||
|
||
### 1. Error masking для необработанных исключений
|
||
|
||
Backend не должен возвращать клиенту внутренние сообщения необработанных `Error` в ответах `500`.
|
||
Подробности должны оставаться в backend-логах. Публичный ответ для unknown/internal errors должен быть
|
||
стабильным и безопасным.
|
||
|
||
### 2. Production configuration hardening
|
||
|
||
Backend должен явно отделять dev defaults от production-конфигурации:
|
||
|
||
- production-запуск не должен молча использовать дефолтные JWT access/refresh secrets;
|
||
- CORS с credentials не должен отражать произвольный origin в production;
|
||
- список допустимых origins должен задаваться конфигурацией окружения.
|
||
|
||
### 3. DTO validation hardening
|
||
|
||
Существующие DTO должны отсеивать заведомо некорректные значения до попадания в service-layer:
|
||
|
||
- даты покупки позиции должны валидироваться как ISO/date строки;
|
||
- количество позиции не должно допускать `0` там, где service-layer уже трактует это как ошибку;
|
||
- изменения должны сохранять существующий успешный пользовательский сценарий для валидных данных.
|
||
|
||
### 4. T-Bank gRPC typed boundary
|
||
|
||
Динамическая природа protobuf/gRPC клиента должна быть локализована в одном typed boundary, чтобы
|
||
доменные broker-сервисы не приводили service clients к `any` напрямую. Цель — улучшить compile-time
|
||
границы без переписывания vendored proto contract и без изменения внешнего T-Bank API behavior.
|
||
|
||
### 5. Cache metadata consistency
|
||
|
||
Cache helper должен сохранять полезность `meta.cachedAt`: cache hit не должен выглядеть как состояние
|
||
без времени кеширования, если timestamp уже можно сохранить вместе с cached payload.
|
||
|
||
### 6. Backend documentation sync
|
||
|
||
Опубликованные docs в `apps/docs/docs/backend/` должны отражать текущее состояние backend после
|
||
закрытых refactor-работ:
|
||
|
||
- split MOEX clients вместо устаревшего `MoexClientService` как единого God Service;
|
||
- актуальный envelope contract;
|
||
- актуальные health response и broker operations sync endpoint.
|
||
|
||
## Ограничения
|
||
|
||
- Не добавлять новые user-facing возможности.
|
||
- Не менять публичный API shape для успешных ответов.
|
||
- Не вводить multi-tenancy или пользовательские T-Bank connections в рамках этой фичи.
|
||
- Не переводить операции T-Bank на локальный read-path в рамках этой фичи.
|
||
- Не менять модель сессий на device/session table в рамках этой фичи.
|
||
- Не менять финансовую модель хранения (`Float`, `Int`, JSON/string fields) и не создавать ledger ADR в
|
||
рамках этой фичи.
|
||
- Не выполнять механическое дробление больших сервисов без проверяемой архитектурной цели.
|
||
- Не редактировать Prisma migrations вручную.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- Необработанные backend exceptions логируются, но `500` response не раскрывает внутренний
|
||
`Error.message`.
|
||
- Production-конфигурация не стартует с дефолтными JWT secrets и не использует wildcard/reflected CORS
|
||
для credentialed requests.
|
||
- DTO портфельных позиций валидируют даты и количество на boundary-уровне; добавлены regression tests.
|
||
- Production-код broker-сервисов не содержит прямых `as any` для получения T-Bank gRPC service clients;
|
||
небезопасное приведение, если оно необходимо, локализовано и покрыто типом/facade.
|
||
- Cache metadata на hit/miss согласована тестами и не ломает `ApiEnvelopePayload`/`ApiResponse` contract.
|
||
- Backend docs обновлены и не ссылаются на удалённый `MoexClientService` как primary abstraction,
|
||
устаревший `/operations/refresh` endpoint или raw health response без envelope.
|
||
- Затронутые backend tests проходят.
|
||
- Backend build проходит.
|
||
- OpenAPI/types обновляются только если реально меняется Swagger contract; `apps/frontend/src/api/types.ts`
|
||
не редактируется вручную.
|
||
|
||
## Out Of Scope
|
||
|
||
- T-Bank data isolation and multi-tenancy.
|
||
- Local T-Bank operations read-path.
|
||
- Device-level sessions, refresh-token rotation и reuse detection.
|
||
- Ledger/financial data model migration.
|
||
- Rate limiting, CSRF и security headers, если они требуют отдельной threat model или middleware policy.
|
||
- Декомпозиция `PortfolioService` или `tbank/` на новые модули без отдельного плана.
|
||
|
||
## Источники
|
||
|
||
- `docs/research/2026-06-25-backend-audit.md`
|
||
- `docs/features/backend-architecture-improvements/spec.md`
|
||
- `docs/features/moex-client-split/spec.md`
|
||
- `docs/features/api-envelope-contract/spec.md`
|
||
- `docs/inbox.md` — раздел «Технический долг — кандидат на следующую итерацию»
|