diff --git a/apps/docs/docs/adr/ADR-013-frontend-fsd-broker-pilot.md b/apps/docs/docs/adr/ADR-013-frontend-fsd-broker-pilot.md new file mode 100644 index 0000000..3923c67 --- /dev/null +++ b/apps/docs/docs/adr/ADR-013-frontend-fsd-broker-pilot.md @@ -0,0 +1,65 @@ +# ADR-013: Frontend FSD broker pilot + +**Статус:** Accepted +**Дата:** 2026-06-20 +**Участники решения:** Product Engineer, Tech Lead + +## Контекст + +Frontend проекта вырос вокруг технических каталогов (`api`, `hooks`, `components`, `pages`). Для +broker-домена это уже приводит к смешению экранной композиции, доменной read-model логики, +query-хуков и локальных UI-блоков. В `docs/inbox.md` зафиксировано направление на переход к +Feature-Sliced Design, но без big-bang переписывания всего frontend. + +Нужна стратегия, которая: + +- уменьшит локальный техдолг в broker UI; +- не развернёт крупный рефакторинг всего frontend сразу; +- даст практический эталон для следующих доменов; +- не приведёт к ложным абстракциям ради формального следования FSD. + +## Рассмотренные варианты + +### Вариант A. Вертикальный broker pilot + +Перенести только broker-домен в FSD-слои, включая pages, widgets, entities и связанные +broker-specific query/read-model части. Остальные домены оставить в текущей структуре. Public API +зафиксировать сразу, а import guards для всего проекта отложить на следующий шаг. + +### Вариант B. FSD-shell без переноса доменной query-логики + +Создать новые FSD-папки только для экранной композиции, но оставить broker API и hooks в +глобальных `src/api` и `src/hooks`. + +### Вариант C. Массовая frontend-миграция + +Одним изменением переносить broker и соседние домены, одновременно нормализуя shared infrastructure +и глобальные import boundaries. + +## Решение + +Принят вариант A: выполнить вертикальный FSD-пилот только для broker-домена и использовать его как +первый эталонный срез новой frontend-архитектуры. + +Решение включает следующие принципы: + +- переход ограничен broker-доменом и не расширяется автоматически на остальные разделы; +- page entrypoints остаются тонкими и не содержат тяжёлую доменную композицию; +- screen-level блоки выделяются отдельно от route entrypoints; +- broker account, broker position и broker operation оформляются как отдельные доменные срезы; +- broker-specific query/hooks/read-model логика переносится ближе к соответствующим срезам; +- truly shared инфраструктура остаётся в shared-области; +- взаимодействие между срезами строится через public API; +- жёсткие import guards и глобальные lint-ограничения выносятся в следующий отдельный шаг после + стабилизации пилота. + +## Последствия + +- У frontend появится рабочий пример FSD-структуры, на который можно опираться при переносе других + доменов. +- Масштаб изменения остаётся управляемым и проверяемым без big-bang миграции. +- Некоторое время в проекте будут сосуществовать старая техническая структура и новый FSD-срез. +- До отдельного шага с import guards архитектурные границы поддерживаются договорённостью, + структурой кода и code review, а не автоматическим правилом. +- Документацию frontend потребуется обновить после реализации пилота, чтобы опубликованная + структура не расходилась с кодом. diff --git a/apps/docs/docs/adr/index.md b/apps/docs/docs/adr/index.md index f2921a9..a9d7669 100644 --- a/apps/docs/docs/adr/index.md +++ b/apps/docs/docs/adr/index.md @@ -14,5 +14,6 @@ | [ADR-010](ADR-010-backend-price-computation) | Accepted | Расчёт цен на backend | | [ADR-011](ADR-011-tbank-invest-grpc) | Accepted | Интеграция с T-Bank Invest через gRPC | | [ADR-012](ADR-012-frontend-broker-account-aggregation) | Accepted | Агрегация сводки брокерских счетов на frontend | +| [ADR-013](ADR-013-frontend-fsd-broker-pilot) | Accepted | Пилотная FSD-миграция broker-домена | Все опубликованные ADR находятся в `apps/docs/docs/adr/` и отображаются в этом Docusaurus-разделе. diff --git a/docs/features/frontend-fsd-broker-pilot/spec.md b/docs/features/frontend-fsd-broker-pilot/spec.md new file mode 100644 index 0000000..5b559e6 --- /dev/null +++ b/docs/features/frontend-fsd-broker-pilot/spec.md @@ -0,0 +1,113 @@ +# Frontend FSD Broker Pilot + +Дата: 2026-06-20 +Статус: согласовано к планированию + +## Контекст + +Frontend проекта исторически организован по техническим каталогам (`api`, `hooks`, `components`, +`pages`). Для broker-домена это уже приводит к размытым границам: экранные блоки, доменные модели, +query-хуки и вспомогательная логика смешаны в одних и тех же областях кода. Это усложняет +поддержку, перенос общих паттернов и дальнейшее масштабирование frontend-архитектуры. + +В `docs/inbox.md` уже зафиксировано направление на постепенный переход к Feature-Sliced Design +(FSD) без big-bang переписывания. В рамках этой фичи broker-домен становится первым пилотным +срезом такого перехода. + +## Иерархия источников + +- Текущая задача пользователя: ограничить техдолг только frontend-частью и начать с FSD-пилота. +- `docs/inbox.md`: направление на постепенную FSD-миграцию и вертикальный перенос broker UI. +- `apps/docs/docs/frontend/overview.md`: опубликованное описание текущей frontend-структуры. +- `AGENTS.md`: требования к SDD, ADR и поэтапному рефакторингу без неявного расширения scope. + +## Цель + +Создать первый законченный вертикальный FSD-срез для broker UI без изменения пользовательского +поведения, чтобы он стал эталонным шаблоном для последующей миграции остальных frontend-доменов. + +## Область изменений + +Фича охватывает только frontend-код, необходимый для broker-домена: + +- broker routes и broker pages; +- broker screen-level блоки и связанные UI-композиции; +- broker-specific query hooks, адаптеры данных и вспомогательную доменную логику; +- broker-specific тесты; +- архитектурную документацию frontend и ADR по выбранной стратегии миграции. + +## Требования + +### 1. Первый FSD-срез ограничен broker-доменом + +Переход на FSD в этой итерации затрагивает только broker-домен. Остальные frontend-домены +(`portfolio`, `screener`, `auth`, общие market pages) продолжают работать в текущей структуре и не +переносятся автоматически в новые слои. + +### 2. Broker-код должен быть разделён по FSD-слоям + +Для broker-домена должна появиться читаемая структура, где: + +- route entrypoints и page-level composition выделены отдельно; +- крупные экранные блоки отделены от страниц; +- broker account, broker position и broker operation представлены как отдельные доменные срезы; +- общие, недоменные примитивы остаются в shared-области. + +### 3. Границы срезов должны быть явными + +Новые broker-срезы должны иметь явные public API, чтобы внешний код не зависел от их внутренней +структуры. Переиспользование между broker-срезами допускается только через публичную точку входа. + +### 4. Query-логика чтения должна следовать доменным границам + +Broker-specific чтение данных не должно оставаться в глобальной технической структуре только по +исторической причине. Query-хуки, адаптеры ответов и близкая к домену read-model логика должны +быть расположены в соответствии с broker-срезами, а не как анонимный общий слой. + +### 5. Общая инфраструктура не должна становиться broker-specific + +Базовый HTTP-клиент, общие UI-примитивы и общие utility-функции сохраняют своё место в общей +shared-области и не дублируются внутри broker-среза. + +### 6. Тесты должны следовать новым границам + +Broker-specific тесты должны быть привязаны к новым slice boundaries, чтобы архитектурные границы +подтверждались не только структурой файлов, но и способом тестирования. + +### 7. Поведение UI не меняется + +FSD-пилот не должен менять пользовательские сценарии broker-раздела. Переход влияет на структуру +кода и организацию зависимостей, но не добавляет новую функциональность и не пересматривает +существующие UX-правила. + +## Ограничения + +- Изменения ограничены frontend-пакетом и опубликованной документацией. +- Frontend не меняет backend API-контракты, Swagger и codegen. +- В этой итерации не вводятся обязательные import guards или ESLint boundaries для всего проекта. +- В этой итерации не выполняется массовая унификация всех shared-компонентов проекта. +- В этой итерации не выполняется lazy-loading routes и не пересматривается глобальная стратегия + TanStack Query. + +## Acceptance Criteria + +- Broker-домен представлен отдельным FSD-пилотом внутри frontend-кода. +- Страницы broker-раздела становятся тонкими route/page entrypoints без смешения с крупной + доменной и screen-level логикой. +- Broker account, broker position и broker operation имеют явные slice boundaries и public API. +- Broker-specific query/hooks/read-model логика больше не остаётся анонимно разбросанной по + глобальным `src/api` и `src/hooks`, если она относится только к broker-домену. +- Общий HTTP-клиент и truly shared primitives остаются в общей shared-области. +- Broker-specific тесты расположены рядом с соответствующими slice boundaries или иным способом + явно следуют новой архитектуре. +- Пользовательское поведение broker UI остаётся эквивалентным до и после миграции. +- Frontend lint, tests и build проходят после рефакторинга. +- Опубликованная документация frontend и ADR отражают выбранную стратегию миграции. + +## Не цели + +- Миграция всего frontend на FSD за один шаг. +- Перенос `portfolio`, `screener`, `auth` и остальных доменов в рамках этой задачи. +- Введение жёстких правил импортов для всего проекта в рамках того же изменения. +- Переписывание backend-контрактов, generated types или T-Bank интеграции. +- Изменение визуального дизайна broker UI как отдельной продуктовой задачи.