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