moex-vibe/docs/features/architecture-quality-backlog/spec.md

Architecture Quality Backlog

Дата: 2026-06-25 Статус: draft

Контекст

В репозитории уже есть несколько завершённых волн архитектурного улучшения, но после них остались:

• разрозненные остатки архитектурного долга во frontend и backend;
• устаревшие или частично противоречивые документы;
• несколько высокосвязанных зон, которые нельзя безопасно рефакторить одной крупной итерацией.

Эта фича не меняет runtime-поведение. Её задача - превратить найденные архитектурные проблемы в нормализованный, приоритизированный backlog для последующих узких refactor-фич.

Цель

Зафиксировать актуальный архитектурный backlog по frontend, backend и проектной документации, разделить его на независимые follow-up фичи и определить порядок их выполнения.

Требования

1. Инвентаризация текущего состояния

Нужно опираться на три источника:

• apps/frontend/src/ - реальные границы слоёв, API слой, session state, query key usage;
• apps/backend/src/ - границы NestJS-модулей, сервисов, Prisma-доступа, DTO и инфраструктурных клиентов;
• docs/ и apps/docs/docs/ - roadmap, epics, feature specs/plans/tasks и опубликованная архитектурная документация.

2. Нормализация находок

Каждый найденный пункт долга должен быть отнесён к одной из категорий:

• уже закрыто;
• устарело и требует пересмотра документации;
• открыто и должно стать отдельной follow-up фичей;
• открыто, но пока должно остаться в backlog без немедленной реализации.

3. Приоритизация

Backlog должен быть упорядочен по следующему правилу:

• сначала низкорисковые и высокосигнальные документы/contract cleanup задачи;
• затем сервисные границы backend;
• затем frontend state/API hardening;
• позже - крупные или спорные refactor-направления.

4. Границы будущих фич

Каждый backlog-item должен быть независимым настолько, чтобы его можно было превратить в отдельную feature-spec без смешивания frontend и backend implementation work в одном change-set.

5. Никаких новых возможностей

Фича не должна:

• менять пользовательские сценарии;
• добавлять новые API;
• менять модель данных;
• вводить новые библиотеки или инфраструктуру;
• исправлять runtime-bug'и вне рамок документации и backlog-формализации.

Предлагаемый backlog

1. Documentation Source-of-Truth Sync

Синхронизировать roadmap, epics и опубликованные architecture docs с текущим состоянием кода, убрать устаревшие статусы и противоречия.

2. Backend Service Boundary Cleanup

Сделать явными границы PortfolioService, TBankModule и связанных сервисов, чтобы последующие refactor-фичи можно было изолировать по доменам.

3. Backend Contract Type-Safety Hardening

Закрыть свободные строки и dynamic access в screener/T-Bank контрактных зонах, не меняя публичный API.

4. Frontend Session Model Simplification

Свести session state к одной понятной точке истины и убрать лишние внутренние импорты между слоями.

5. Frontend Query-Key and API Wrapper Hardening

Нормализовать query key factories и повысить устойчивость API request layer к contract drift.

Ограничения

• Только docs/backlog scope.
• Не трогать runtime-код в рамках этой фичи.
• Не объединять в один backlog-item несвязанные frontend и backend работы.
• Не добавлять новые продуктовые требования.

Критерии приемки

• Есть один согласованный backlog с приоритетом и кратким обоснованием по каждому пункту.
• Для каждого backlog-item указаны:
  • цель;
  • риск;
  • зависимости;
  • ожидаемый артефакт follow-up фичи;
  • причина, почему item не закрыт уже сейчас.
• Документация не противоречит текущему коду и уже завершённым refactor-волнам.
• Backlog отражён в docs/roadmap.md и связан с релевантными epics/feature docs.
• В рамках этой фичи не изменены файлы apps/frontend/src/** и apps/backend/src/**.