docs: define frontend fsd broker pilot
This commit is contained in:
parent
52ebe3256d
commit
3b618d3da0
65
apps/docs/docs/adr/ADR-013-frontend-fsd-broker-pilot.md
Normal file
65
apps/docs/docs/adr/ADR-013-frontend-fsd-broker-pilot.md
Normal file
@ -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 потребуется обновить после реализации пилота, чтобы опубликованная
|
||||||
|
структура не расходилась с кодом.
|
||||||
@ -14,5 +14,6 @@
|
|||||||
| [ADR-010](ADR-010-backend-price-computation) | Accepted | Расчёт цен на backend |
|
| [ADR-010](ADR-010-backend-price-computation) | Accepted | Расчёт цен на backend |
|
||||||
| [ADR-011](ADR-011-tbank-invest-grpc) | Accepted | Интеграция с T-Bank Invest через gRPC |
|
| [ADR-011](ADR-011-tbank-invest-grpc) | Accepted | Интеграция с T-Bank Invest через gRPC |
|
||||||
| [ADR-012](ADR-012-frontend-broker-account-aggregation) | Accepted | Агрегация сводки брокерских счетов на frontend |
|
| [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-разделе.
|
Все опубликованные ADR находятся в `apps/docs/docs/adr/` и отображаются в этом Docusaurus-разделе.
|
||||||
|
|||||||
113
docs/features/frontend-fsd-broker-pilot/spec.md
Normal file
113
docs/features/frontend-fsd-broker-pilot/spec.md
Normal file
@ -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 как отдельной продуктовой задачи.
|
||||||
Loading…
x
Reference in New Issue
Block a user