diff --git a/docs/features/architecture-quality-backlog/plan.md b/docs/features/architecture-quality-backlog/plan.md new file mode 100644 index 0000000..4a7dadb --- /dev/null +++ b/docs/features/architecture-quality-backlog/plan.md @@ -0,0 +1,111 @@ +# Architecture Quality Backlog Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** turn the current frontend/backend architecture audit into a prioritized, docs-backed backlog of follow-up refactor features. + +**Architecture:** this feature is docs-only. We will not change runtime code; instead we will reconcile source-of-truth docs with the current codebase, classify findings by subsystem, and publish a backlog that can be split into future single-subsystem refactor features. + +**Tech Stack:** Markdown docs in `docs/`, published Docusaurus docs in `apps/docs/docs/`, existing repo search tooling. + +--- + +### Task 1: Consolidate source material + +**Files:** +- Read: `docs/research/2026-06-25-backend-audit.md` +- Read: `docs/features/frontend-debt-audit/spec.md` +- Read: `docs/features/backend-architecture-refactor/spec.md` +- Read: `apps/docs/docs/frontend/overview.md` +- Read: `apps/docs/docs/backend/modules.md` +- Read: `docs/roadmap.md` + +- [ ] **Step 1: Capture current architecture findings** + +Use the existing audit docs plus current source/docs to confirm which items are already closed, which are stale in docs, and which are still open. + +- [ ] **Step 2: Check for overlap with completed work** + +Verify that the backlog does not reintroduce items already covered by completed refactor docs or published architecture pages. + +### Task 2: Write the backlog spec + +**Files:** +- Create: `docs/features/architecture-quality-backlog/spec.md` + +- [ ] **Step 1: Write the backlog scope** + +Document that this feature is docs-only and only produces a prioritized backlog, not runtime code changes. + +- [ ] **Step 2: List the backlog items** + +Describe the five backlog items in priority order: + +```markdown +1. Documentation Source-of-Truth Sync +2. Backend Service Boundary Cleanup +3. Backend Contract Type-Safety Hardening +4. Frontend Session Model Simplification +5. Frontend Query-Key and API Wrapper Hardening +``` + +- [ ] **Step 3: State the acceptance criteria** + +Require explicit risk/dependency notes for every backlog item and a no-runtime-code-change constraint. + +### Task 3: Write the execution plan + +**Files:** +- Create: `docs/features/architecture-quality-backlog/plan.md` + +- [ ] **Step 1: Describe the doc-only architecture** + +Explain that the implementation is a documentation workflow: inventory, classify, prioritize, publish. + +- [ ] **Step 2: Define the file responsibilities** + +State which docs are the source material, which doc is the canonical backlog, and which docs will be updated to reflect it. + +- [ ] **Step 3: Add the validation checklist** + +Require a final consistency pass against code and existing docs before the backlog is considered ready. + +### Task 4: Write the task breakdown + +**Files:** +- Create: `docs/features/architecture-quality-backlog/tasks.md` + +- [ ] **Step 1: Create small independent doc tasks** + +Break the work into small, reviewable documentation tasks: + +```markdown +- [ ] Inventory the current frontend/backend architecture debt +- [ ] Remove completed or stale items from the backlog +- [ ] Prioritize the remaining backlog by risk and dependency +- [ ] Cross-link the backlog with roadmap and epics +- [ ] Run a final docs consistency review +``` + +- [ ] **Step 2: Ensure no code tasks are listed** + +This feature must not include implementation tasks for `apps/frontend/src/**` or `apps/backend/src/**`. + +- [ ] **Step 3: Reference the docs that will be linked** + +Use `docs/roadmap.md` plus the relevant epic/feature docs as the cross-link targets for the published backlog. + +### Task 5: Final review + +**Files:** +- Read: `docs/features/architecture-quality-backlog/spec.md` +- Read: `docs/features/architecture-quality-backlog/plan.md` +- Read: `docs/features/architecture-quality-backlog/tasks.md` + +- [ ] **Step 1: Check for scope creep** + +Ensure the documents describe backlog creation only, not code refactoring. + +- [ ] **Step 2: Check for contradictions** + +Verify that the priority order, scope, and acceptance criteria match across all three files. diff --git a/docs/features/architecture-quality-backlog/spec.md b/docs/features/architecture-quality-backlog/spec.md new file mode 100644 index 0000000..d8a4762 --- /dev/null +++ b/docs/features/architecture-quality-backlog/spec.md @@ -0,0 +1,102 @@ +# 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/**`. diff --git a/docs/features/architecture-quality-backlog/tasks.md b/docs/features/architecture-quality-backlog/tasks.md new file mode 100644 index 0000000..4cbd2a1 --- /dev/null +++ b/docs/features/architecture-quality-backlog/tasks.md @@ -0,0 +1,7 @@ +# Architecture Quality Backlog Tasks + +- [ ] Audit current frontend/backend architecture findings and classify them against existing docs. +- [ ] Remove items already covered by completed refactors or stale documentation. +- [ ] Prioritize the remaining debt into a single ordered backlog. +- [ ] Link each backlog item to a future follow-up feature boundary. +- [ ] Verify the backlog is docs-only and does not require runtime code changes.