114 lines
8.3 KiB
Markdown
114 lines
8.3 KiB
Markdown
# 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 как отдельной продуктовой задачи.
|