diff --git a/docs/epics/FrontendDebtBacklog.md b/docs/epics/FrontendDebtBacklog.md new file mode 100644 index 0000000..6652fa3 --- /dev/null +++ b/docs/epics/FrontendDebtBacklog.md @@ -0,0 +1,17 @@ +# Frontend Debt Backlog + +Статус: запланировано + +Порядок реализации: + +1. `frontend-docs-sync` — сначала синхронизируем docs, чтобы backlog и реальность совпадали. +2. `frontend-infrastructure-hardening` — затем стабилизируем tooling и окружение для следующих работ. +3. `frontend-shared-boundary-cleanup` — после этого сужаем shared/public API и границы слоёв. +4. `frontend-test-hygiene` — в конце нормализуем test helpers и conventions на уже стабилизированной базе. + +Features: +- [ ] [frontend-debt-audit](../features/frontend-debt-audit/spec.md) — аудит frontend-техдолга и приоритизация backlog +- [ ] [frontend-docs-sync](../features/frontend-docs-sync/spec.md) — синхронизация inbox/roadmap и устаревшей frontend-документации +- [ ] [frontend-infrastructure-hardening](../features/frontend-infrastructure-hardening/spec.md) — завершение infrastructure/tooling debt +- [ ] [frontend-shared-boundary-cleanup](../features/frontend-shared-boundary-cleanup/spec.md) — сужение shared/public API и границ слоёв +- [ ] [frontend-test-hygiene](../features/frontend-test-hygiene/spec.md) — упрощение и нормализация frontend-test infrastructure diff --git a/docs/features/frontend-debt-audit/plan.md b/docs/features/frontend-debt-audit/plan.md new file mode 100644 index 0000000..1269c8f --- /dev/null +++ b/docs/features/frontend-debt-audit/plan.md @@ -0,0 +1,114 @@ +# Frontend Debt Audit and 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:** Audit the current frontend technical debt, classify what is closed vs open, and turn the open work into a prioritized backlog with roadmap/inbox sync. + +**Architecture:** This is a docs-first workflow. First collect evidence from the codebase and existing docs, then synthesize the findings into a compact backlog, then update `inbox.md` and `roadmap.md` so the project docs match the current frontend state. No runtime code changes are part of this feature. + +**Tech Stack:** Markdown docs, git, targeted source searches, repo conventions, existing frontend specs/plans. + +--- + +### Task 1: Collect audit evidence + +**Files:** +- Read: `docs/inbox.md` +- Read: `docs/roadmap.md` +- Read: `docs/features/frontend-fsd-cleanup/spec.md` +- Read: `docs/features/frontend-fsd-cleanup/plan.md` +- Read: `docs/features/frontend-fsd-final/spec.md` +- Read: `docs/features/frontend-fsd-final/plan.md` +- Read: `docs/features/frontend-infrastructure-tooling/spec.md` +- Read: `docs/features/frontend-infrastructure-tooling/plan.md` +- Read: `apps/frontend/package.json` +- Search: `apps/frontend/src/**/*` + +- [ ] **Step 1: Verify the current frontend debt signals** + +Run: + +```bash +rg -n "TODO|FIXME|@ts-ignore|eslint-disable|\.\./" apps/frontend/src docs/features +``` + +Expected: either no matches in `apps/frontend/src`, or matches that are explicitly explainable as already planned work in `docs/features/`. + +- [ ] **Step 2: Read the current frontend specs and roadmap entries** + +Run: + +```bash +git grep -n "frontend" docs/features docs/inbox.md docs/roadmap.md +``` + +Expected: a compact list of the currently documented frontend workstreams and cleanup items. + +### Task 2: Synthesize the backlog + +**Files:** +- Modify: `docs/features/frontend-debt-audit/spec.md` +- Modify: `docs/features/frontend-debt-audit/plan.md` +- Create/Modify: `docs/features/frontend-debt-audit/tasks.md` + +- [ ] **Step 1: Record the audit clusters in the feature docs** + +Capture the open-work clusters as separate follow-up candidates under the `Frontend Debt Backlog` epic, at minimum: + +- docs synchronization / stale specification cleanup; +- frontend infrastructure hardening; +- shared API and boundary cleanup. +- frontend test hygiene. + +Keep each cluster independent and do not merge implementation work into the audit feature itself. + +- [ ] **Step 2: Write the audit tasks file** + +`docs/features/frontend-debt-audit/tasks.md` should contain a checkbox list with the following work items: + +1. reconcile current state against docs; +2. classify open vs closed items; +3. split the open items into follow-up features; +4. update inbox and roadmap; +5. verify the documentation diff is self-consistent. + +### Task 3: Sync inbox and roadmap + +**Files:** +- Modify: `docs/inbox.md` +- Modify: `docs/roadmap.md` + +- [ ] **Step 1: Add the audit note to inbox** + +Add a short inbox entry that captures the working hypothesis: frontend maintenance should now be handled as a small set of explicit follow-up features instead of one monolithic cleanup effort. + +- [ ] **Step 2: Add or update the roadmap candidate entry** + +Add a roadmap item for `frontend-debt-audit` and, if needed, keep the existing infrastructure tooling entry as a follow-up candidate rather than a live implementation promise. + +### Task 4: Self-check the documentation set + +**Files:** +- Read: `docs/features/frontend-debt-audit/spec.md` +- Read: `docs/features/frontend-debt-audit/plan.md` +- Read: `docs/features/frontend-debt-audit/tasks.md` +- Read: `docs/inbox.md` +- Read: `docs/roadmap.md` + +- [ ] **Step 1: Check for contradictions** + +Confirm that the spec only promises audit/backlog work and does not imply code changes. + +- [ ] **Step 2: Check for missing follow-up clusters** + +Confirm that every open frontend debt item from the audit is mapped into one of the follow-up clusters or explicitly marked as deferred. + +- [ ] **Step 3: Verify the diff is docs-only** + +Run: + +```bash +git diff --name-only +``` + +Expected: only files under `docs/` changed. diff --git a/docs/features/frontend-debt-audit/spec.md b/docs/features/frontend-debt-audit/spec.md new file mode 100644 index 0000000..37e80d1 --- /dev/null +++ b/docs/features/frontend-debt-audit/spec.md @@ -0,0 +1,88 @@ +# Frontend Debt Audit and Backlog + +Дата: 2026-06-23 +Статус: спецификация + +## Контекст + +Frontend уже прошёл крупные волны миграции: FSD-рефакторинг, дизайн-система, тестовая инфраструктура, +tooling и часть архитектурных cleanup-задач. После этого в репозитории осталось два типа +техдолга: + +1. реальные открытые хвосты, которые ещё нужно довести до конца; +2. устаревшие или слишком широкие документы, которые описывают уже изменившееся состояние кода. + +Сейчас нужна отдельная SDD-фича, которая не внедряет поведение, а проводит аудит текущего frontend +состояния и превращает его в приоритизированный backlog для следующих узких фич. + +## Цель + +Зафиксировать актуальное состояние frontend-техдолга, отделить завершённые и устаревшие пункты от +реально открытых, и сформировать приоритизированный backlog следующих фич с понятными границами. + +Этот аудит обслуживает отдельный epic `Frontend Debt Backlog` и должен приводить к разложению открытого +долга на следующие независимые фичи: + +- `frontend-docs-sync` +- `frontend-infrastructure-hardening` +- `frontend-shared-boundary-cleanup` +- `frontend-test-hygiene` + +## Требования + +### 1. Инвентаризация текущего состояния + +Нужно проверить актуальное состояние frontend по трём источникам: + +- `apps/frontend/src/` — код, экспорты, зависимости слоёв, test helpers, API surface; +- `docs/features/` — существующие спецификации, планы и задачи по frontend; +- `docs/inbox.md` и `docs/roadmap.md` — гипотезы и уже зафиксированные кандидатные работы. + +Аудит должен явно разделить находки на категории: + +- уже закрыто; +- ещё открыто; +- устарело и подлежит пересмотру; +- требует отдельной новой фичи. + +### 2. Приоритизация открытого долга + +Все открытые пункты должны быть сгруппированы в небольшие независимые фичи. Для каждой группы нужно +зафиксировать: + +- цель; +- почему это долг; +- примерный риск/сложность; +- рекомендуемый порядок реализации; +- какие текущие документы это затрагивает. + +### 3. Синхронизация проектной доки + +Результаты аудита должны быть отражены в проектных документах: + +- `docs/inbox.md` — как источник идей и низкосигнальных заметок; +- `docs/roadmap.md` — как список следующих фич и кандидатов; +- `docs/features/frontend-debt-audit/*` — как SDD-артефакты самой audit-фичи. + +Плюс результаты аудита должны служить входом для эпика `Frontend Debt Backlog`. + +### 4. Никаких изменений поведения + +Эта фича не меняет runtime-поведение frontend, не трогает backend и не вводит продуктовые улучшения +сверх формализации найденного долга. + +## Ограничения + +- Только frontend-область и связанные с ней docs. +- Не выполнять миграции кода в рамках этой фичи. +- Не смешивать аудит с внедрением follow-up задач. +- Не дублировать уже закрытые FSD/infra cleanup работы как новые задачи. + +## Критерии приемки + +- Зафиксирован перечень проверенных областей frontend-аудита с доказательствами по каждой области. +- Для каждого открытого debt-item есть приоритет и рекомендация по разбиению на следующую фичу. +- В `docs/inbox.md` добавлена актуальная заметка о frontend debt backlog. +- В `docs/roadmap.md` добавлен новый кандидат или уточнён существующий блок, отражающий audit-backlog. +- `docs/features/frontend-debt-audit/plan.md` и `tasks.md` согласованы с результатом аудита. +- Не изменены файлы `apps/frontend/src/**`. diff --git a/docs/features/frontend-debt-audit/tasks.md b/docs/features/frontend-debt-audit/tasks.md new file mode 100644 index 0000000..99da6b1 --- /dev/null +++ b/docs/features/frontend-debt-audit/tasks.md @@ -0,0 +1,28 @@ +# Frontend Debt Audit and Backlog — tasks + +Статус: pending + +## 1. Снять актуальное состояние frontend-долга + +- [ ] Проверить `docs/inbox.md`, `docs/roadmap.md` и существующие frontend specs/plans на предмет устаревших или пересекающихся пунктов +- [ ] Пройтись по `apps/frontend/src/` и подтвердить, что legacy FSD-cleanup хвостов больше нет +- [ ] Зафиксировать список реально открытых debt-сигналов и отметить, какие из них уже покрыты существующими фичами + +## 2. Сформировать backlog follow-up фич + +- [ ] Сгруппировать открытые пункты в независимые follow-up фичи +- [ ] Назначить приоритеты `P0/P1/P2` для каждой группы +- [ ] Отметить зависимости и порядок выполнения между группами +- [ ] Подтвердить, что follow-up фичи оформлены как части epic `Frontend Debt Backlog` + +## 3. Синхронизировать проектную документацию + +- [ ] Обновить `docs/inbox.md` новыми заметками по frontend maintenance backlog +- [ ] Обновить `docs/roadmap.md` новым candidate-элементом или уточнением существующего +- [ ] Проверить, что формулировки не обещают внедрение кода внутри audit-фичи + +## 4. Финальная проверка + +- [ ] Убедиться, что в рамках этой фичи не изменялись файлы `apps/frontend/src/**` +- [ ] Проверить `git diff --name-only` и убедиться, что изменены только `docs/`-файлы +- [ ] Проверить, что спецификация, план и задачи не противоречат друг другу diff --git a/docs/features/frontend-docs-sync/spec.md b/docs/features/frontend-docs-sync/spec.md new file mode 100644 index 0000000..ff08c6b --- /dev/null +++ b/docs/features/frontend-docs-sync/spec.md @@ -0,0 +1,58 @@ +# Frontend Docs Sync + +Дата: 2026-06-23 +Статус: спецификация + +## Контекст + +Frontend-архитектура уже сильно изменилась: большая часть FSD-миграции завершена, часть cleanup +работ закрыта, а некоторые документы всё ещё описывают промежуточное состояние проекта. Из-за этого +новому участнику сложно понять, какие frontend-решения уже живые, какие только планировались, а +какие нужно держать как backlog. + +Эта фича нужна, чтобы привести `docs/inbox.md`, `docs/roadmap.md` и frontend-спецификации к текущему +состоянию репозитория без изменения runtime-поведения приложения. + +## Цель + +Синхронизировать frontend-документацию с текущим состоянием кода и перенести устаревшие идеи в +явный backlog, чтобы docs отражали реальность, а не промежуточный план миграции. + +## Требования + +### 1. Обновить inbox + +`docs/inbox.md` должен содержать только идеи и гипотезы, которые ещё не оформлены в спецификации или +roadmap. Устаревшие миграционные заметки нужно либо удалить, либо явно пометить как уже покрытые +отдельной фичей. + +### 2. Обновить roadmap + +`docs/roadmap.md` должен содержать только актуальные кандидаты следующих фич. Элементы, которые уже +превратились в отдельные SDD-фичи, не должны дублироваться как абстрактные заметки. + +### 3. Согласовать frontend feature docs + +Спецификации по frontend должны ссылаться друг на друга так, чтобы было ясно: + +- что уже завершено; +- что ещё в backlog; +- какие фичи являются follow-up к audit/backlog эпикам. + +### 4. Не менять продуктовое поведение + +Эта фича касается только документации и статуса работ. Код frontend и backend не меняется. + +## Ограничения + +- Только `docs/`. +- Не создавать дублирующие записи о тех же идеях в inbox и roadmap. +- Не смешивать документационный sync с реализацией кода. + +## Критерии приемки + +- `docs/inbox.md` отражает только живые идеи и не дублирует завершённые frontend cleanup-фичи. +- `docs/roadmap.md` содержит актуальные candidate features без устаревших промежуточных формулировок. +- Все новые frontend-fича документы ссылаются на общий epic `Frontend Debt Backlog`. +- Документация по frontend не противоречит текущему состоянию `apps/frontend/src/`. +- Не изменены runtime-файлы приложения. diff --git a/docs/features/frontend-infrastructure-hardening/spec.md b/docs/features/frontend-infrastructure-hardening/spec.md new file mode 100644 index 0000000..754d60c --- /dev/null +++ b/docs/features/frontend-infrastructure-hardening/spec.md @@ -0,0 +1,55 @@ +# Frontend Infrastructure Hardening + +Дата: 2026-06-23 +Статус: спецификация + +## Контекст + +Во frontend уже есть базовый tooling stack, но инфраструктурные решения собраны в несколько разных +зон: HTTP-клиент, mock-режим, env validation, routing, linting/formatting и OpenAPI-generated types. +После крупных миграций осталось несколько точек, которые нужно довести до устойчивого состояния и +убрать смешение временных и целевых решений. + +Эта фича не про новый user-facing функционал. Она закрывает инфраструктурный долг, который мешает +предсказуемым локальным запускам, стабильной разработке и ясности контрактов. + +## Цель + +Стабилизировать frontend infrastructure/tooling так, чтобы ключевые developer workflows были +детерминированными и не опирались на временные компромиссы. + +## Требования + +### 1. Browser mock mode + +Должен быть documented и поддержан browser mock mode для локального запуска frontend без backend при +явном флаге окружения. Этот режим не должен влиять на обычный production/dev without mock сценарий. + +### 2. Env validation + +Все обязательные frontend env variables должны проверяться при старте приложения, чтобы ошибки +конфигурации были видимы сразу, а не проявлялись как runtime failure. + +### 3. Tooling consistency + +Скрипты lint/test/build должны оставаться согласованными с реальной структурой проекта и не должны +ссылаться на устаревшие команды или несуществующие файлы. + +### 4. Contract freshness + +Frontend tooling должен опираться на актуальные generated API types и public API entrypoints, а не на +устаревшие type shims или временные compatibility слои. + +## Ограничения + +- Не менять бизнес-логику frontend. +- Не переписывать routing architecture целиком в рамках этой фичи. +- Не затрагивать backend кроме чтения публичных контрактов. + +## Критерии приемки + +- Browser mock mode описан и согласован с текущими dev scripts. +- Валидация env обязательных переменных формализована и не конфликтует с текущим startup flow. +- Frontend tooling docs и scripts отражают реальное состояние проекта. +- Ссылки на API types и client surface не используют устаревшие документы. +- Не изменены runtime-scenarios пользовательского приложения. diff --git a/docs/features/frontend-shared-boundary-cleanup/spec.md b/docs/features/frontend-shared-boundary-cleanup/spec.md new file mode 100644 index 0000000..c946df5 --- /dev/null +++ b/docs/features/frontend-shared-boundary-cleanup/spec.md @@ -0,0 +1,53 @@ +# Frontend Shared Boundary Cleanup + +Дата: 2026-06-23 +Статус: спецификация + +## Контекст + +FSD-миграция уже убрала большую часть legacy-imports, но после крупного рефакторинга обычно остаются +тонкие границы, которые сложно заметить без отдельного аудита: слишком широкий `shared` public API, +дублирующие экспортные точки, и отдельные cross-layer или cross-entity dependencies, которые формально +работают, но ухудшают архитектурную ясность. + +Эта фича нужна, чтобы сузить shared/public surface и убрать архитектурные серые зоны без изменения +поведения экранов. + +## Цель + +Сделать frontend layer boundaries более явными: shared должен экспортировать только truly shared +поверхность, а доменные сущности и виджеты должны общаться через свои public entrypoints. + +## Требования + +### 1. Сузить shared public API + +`apps/frontend/src/shared/api` должен содержать только то, что действительно используется как shared +инфраструктура. Доменная поверхность должна быть разнесена по своим entity API/entrypoints. + +### 2. Устранить boundary ambiguity + +Любые архитектурно сомнительные cross-entity или cross-widget зависимости должны либо быть убраны, +либо явно перенесены на public barrel entrypoints. + +### 3. Сохранить runtime behavior + +Изменения должны быть ограничены реорганизацией импортов и export boundaries. Бизнес-логика и UI +поведение не меняются. + +### 4. Зафиксировать public API правила + +Фича должна завершиться с понятным описанием того, что считается public API каждого frontend слоя. + +## Ограничения + +- Не выполнять UI redesign. +- Не менять backend contracts. +- Не переписывать feature logic вне boundary cleanup. + +## Критерии приемки + +- Shared API surface стал уже и понятнее, чем до фичи. +- Cross-layer / cross-entity зависимости используют public barrels или удалены. +- Описание public API слоёв frontend обновлено в docs. +- Поведение UI и API-контракты не изменились. diff --git a/docs/features/frontend-test-hygiene/spec.md b/docs/features/frontend-test-hygiene/spec.md new file mode 100644 index 0000000..33bb767 --- /dev/null +++ b/docs/features/frontend-test-hygiene/spec.md @@ -0,0 +1,53 @@ +# Frontend Test Hygiene + +Дата: 2026-06-23 +Статус: спецификация + +## Контекст + +Во frontend уже есть Vitest, Testing Library и MSW, но после нескольких фаз миграции тестовая +инфраструктура может накопить лишние абстракции, дублирующиеся helpers и разъехавшиеся conventions. +Это не проблема покрытия как такового, а проблема ясности, локальности и поддержки тестов. + +Эта фича нужна, чтобы тестовый слой оставался простым: тесты должны быть рядом с кодом, helpers должны +быть минимальными, а сетевые и контекстные зависимости должны быть предсказуемыми. + +## Цель + +Упростить и нормализовать frontend test infrastructure так, чтобы тесты было легче писать, читать и +поддерживать без изменения продуктового поведения. + +## Требования + +### 1. Test helpers stay minimal + +Общие test helpers должны содержать только действительно shared тестовую инфраструктуру. Дублирующие +или слишком широкие обёртки нужно убрать или сузить. + +### 2. Testing conventions stay consistent + +Frontend тесты должны следовать единым правилам по расположению, mock strategy, QueryClient setup и +MSW usage. Новые тестовые паттерны не должны вводить отдельные локальные договорённости без причины. + +### 3. Coverage is preserved + +Рефакторинг тестовой инфраструктуры не должен уменьшать существующее покрытие или ломать тесты в +колокации с кодом. + +### 4. No production behavior changes + +Фича касается только test layer. Production code changes допускаются только если они неизбежны для +упрощения тестовой поверхности, и тогда должны быть минимальными. + +## Ограничения + +- Не переписывать всю тестовую базу целиком. +- Не добавлять новую тестовую платформу. +- Не менять backend test strategy. + +## Критерии приемки + +- Test helpers и wrappers стали проще или уже, чем до фичи. +- Основные frontend тесты продолжают проходить. +- Тестовая документация описывает актуальные conventions. +- Не изменено пользовательское runtime-поведение. diff --git a/docs/inbox.md b/docs/inbox.md index 0c77c03..65355bd 100644 --- a/docs/inbox.md +++ b/docs/inbox.md @@ -192,6 +192,16 @@ cash flow, бюджеты, аналитика, прогнозы и автома `SharePositionTable` → `BondPositionTable`, сначала уточнив минимальный API `DataTable` на основе реальных кейсов. +### Провести аудит frontend debt backlog + +- Сначала зафиксировать текущий frontend debt как отдельную audit-фичу, а не как одну большую + cleanup-инициативу. +- Разделить открытые пункты на небольшие follow-up фичи: docs sync, infrastructure hardening, shared + API/boundary cleanup. +- Не смешивать аудит с реализацией follow-up задач; audit должен только подтвердить актуальное + состояние и приоритеты. +- Эпик для этой декомпозиции: `Frontend Debt Backlog`. + ### Исследовать Backend-Driven UI - Рассматривать BDUI как исследовательскую гипотезу, а не выбранную целевую архитектуру. diff --git a/docs/roadmap.md b/docs/roadmap.md index 322720b..b6fa4e8 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -83,6 +83,16 @@ Roadmap отражает порядок продуктовой работы, н ## Кандидаты следующих фич +- [ ] [Frontend debt audit and backlog](features/frontend-debt-audit/spec.md) — audit текущего + frontend-техдолга, разделение open items на follow-up фичи, синхронизация inbox/roadmap. +- [ ] [Frontend docs sync](features/frontend-docs-sync/spec.md) — синхронизация inbox/roadmap и + устаревшей frontend-документации. +- [ ] [Frontend infrastructure hardening](features/frontend-infrastructure-hardening/spec.md) — + завершение infrastructure/tooling debt. +- [ ] [Frontend shared boundary cleanup](features/frontend-shared-boundary-cleanup/spec.md) — + сужение shared/public API и границ слоёв. +- [ ] [Frontend test hygiene](features/frontend-test-hygiene/spec.md) — упрощение и нормализация + frontend test infrastructure. - [ ] [Миграция таблиц на дизайн-систему](features/table-migration/spec.md) — перевести legacy-таблицы на `DataTable` поверх `TanStack Table`. - [ ] Аналитика портфеля Phases 2–3 — дивидендный доход, сравнение с target allocation.