moex-vibe/docs/features/frontend-libraries/plan.md

plan.md - План модернизации инфраструктуры фронтенда

Обзор

Последовательно внедрим девять библиотек для современной инфраструктуры, чтобы достичь максимальной проработки, стабильности кода, делать быстрые итерации спецификаций и избежать технического долга.

Глобальные настройки

Настройка реактивного корневого провайдера

1. Внедрим лаконичный универсальный инсталлятор AppProviders, который подключает TanStack Query, Zustand-состояние (реактивное), MUI ThemeProvider и Dayjs.
2. Оставим существующую SessionProvider в рабочем состоянии, чтобы избежать перебоев, и подключим её к Zustand для единообразия (этап 3).

Паттерны кода и разработки

Формы по шаблону

• Валидация по шину ( Zod ) реализуется через react-hook-form.
• В стилизованном виде можно динамически импортировать Controller component.

Удобство работы с таблицами

• Подготовим изолированные хуки для TanStack Query для списков (например, useStocksQuery).
• Создадим компонент обертку, который обрабатывает пагинацию/сортировку/API в соответствии с API заданным контрактом.

Аутентификация

• Маленькое, независимое хранилище системных токенов (authStore) вместе с конфигурацией клиента в одном месте.

Работа с данными

• Упростим всю работу с датами через один экспорт, включающий шаблоны локализации, форматирования и хуков.

Этапы работы

Этап 1: Подготовка и проверка

• Создать ветку codex/frontend-libraries-setup и подготовить структуру артефактов.
• Проанализировать текущие src/app/providers/ и выбрать легкий путь к интеграции Zustand.
• Настроить Vitest конфигурацию для новых библиотек (dayjs, clsx, zod).
• Запустить существующие тесты, чтобы убедиться, что выполнение базовой сборки не создает проблемы.

Этап 2: Внедрение HTTP-клиента (ky)

• Создать src/shared/api/kyClient.ts с клиентским хуком, поддерживающим интерцепторы (auth + refresh-token).
• Перенести configureAuth, getAccessToken в authStore.ts, сгенерировать интерфейс: { onUnauthorized: () => void, getAccessToken: () => string | null }.
• Переписать src/shared/api/client.ts на использование kyApi под капотом, сохранить тот же внешний интерфейс (request, getHealth).
• Убедиться, что авторизационный поток для старых страниц остается неизменным (т.е., SessionProvider обращается к authStore для токенов).
• Записать целевую пользовательскую спецификацию для этого этапа, сослаться на features/frontend-fsd-cleanup/spec.md, чтобы не создавать дублирующую спецификацию.

Этап 3: Внедрение Zustand stores

• Создать src/entities/session/model/sessionStore.ts — состояние авторизации с хуком useSessionStore и TypeScript типизацией.
• Пересоздать SessionProvider на базе sessionStore. Элиминировать хуки useState, useEffect; заменить устаревшие SessionContext на хуки useSessionStore при необходимости.
• Создать src/entities/session/features/authStore.ts — отдельные эвенты для логина/логаута.
• Обновить всю сеть авторизации (pages/login, pages/register, entities/session/бизнес), чтобы они напрямую взаимодействовали со Zustand, удаляя реактивные обработчики и API-оболочку!
• Обновить экспорты SessionProvider, добавить хук useSession в качестве обратной совместимости.

Этап 4: Внедрение MUI + тему

• Установить react-is@^18.3.1 (как указано в документации MUI v7). Используйте existing получаемый автоматом package.json.
• Создать src/app/styles/theme.ts с createTheme({ cssVariables: true }). Моно-поддержка CSS-переменных + будущая реализация mode: dark/light через colorSchemes.
• Добавить ThemeProvider в AppProviders.tsx.
• Создать утилиту withTheme в src/shared/lib/theme/ для фоновой интеграции.
• Загрузить существующий пакет иконок в src/assets/icons/ (используйте возвращенный список mui-icons).
• Пример: Отрефакторируйте компоненты в src/pages/login на использование MUI Button + TextField.

Этап 5: Внедрение даты (dayjs)

• Создать src/shared/lib/dates/index.ts с хуком мини-интерфайса (например, formatDate, formatRelativeTime).
• Поэтапно загрузить шаблоны в компоненты, где используются паттерны new Date(...). Рефакторинг в формате formatDate(date, 'DD.MM.YYYY').
• Добавить зависимости в фазе :watch тестирования.

Этап 6: Внедрение форм (react-hook-form + zod)

• Создать шаблоны схем в src/shared/lib/schema/.
• Добавить компонент обертку FormField для MUI TextField в src/shared/ui/form-field. Упростить работу с полями, спинами валидации.
• Реализовать компоненты форм в src/features/auth/login.tsx на основе шаблонов react-hook-form.
• Сделать «миграцию утечек» для старых форм, где требуется обработка пошагово.

Этап 7: Внедрение утилиты clsx

• Создать src/shared/lib/styles/clsx.ts с помощью функции cn + ее реэкспорта в src/shared/lib/styles.
• Произвести поэтапный поиск className="class1 class2" && condition && "class3" в компонентах, заменить на cn(...).
• Обновить все шаблоны компонентов в окрестностях _ui.

Этап 8: Внедрение таблиц (TanStack react-table)

• Создать хуки настройки таблицы в src/shared/ui/table/tanstack-table-config.ts с конфигурацией внешнего вида (сортировка, пагинация, фильтрация, реактивное обновление данных).
• Создать компоненты обертки для пагинации/столбцов (Table.tsx, Pagination.tsx). Использовать согласно паттернам FSD.
• Внедрить «компонент столбцов» в любой таблицы (например, отображение позиций брокеров, данных по облигациям).
• Разместить таблицу в src/pages/positions.

Этап 9: Преимущества кодовой базы

• Устойчивое управление кодом: проверить, что каждый файл взаимодействует со строго одним слоем FSD.
• Улучшить покрытие тестов для новых компонентов/хуков.
• Настроить наказания кода: нет длинной функции (max-lines-per-function < 100), no-console во время сборки.
• Убедиться, что lint и typecheck проходят (npm run lint).
• Записать ежедневный документ в days-of-progress/ с метаданными каждого принятого изменения.

Этап 10: Валидация конечного результата

• Запустить полный набор тестов (npm run test) – убедиться, что >90% покрытие кода.
• Запустить npm run build frontend, убедиться, что сборка проходит успешно.
• Запустить npm run lint и lint-staged — устранить проблемы.
• Улучшить документацию в apps/docs/docs/frontend/, связанную с новыми библиотеками (обновить страницы документации).
• Создать карточку Pull Request, субъект: feat: add modern frontend infrastructure (ky, Zustand, MUI, dayjs, react-hook-form, zod, clsx, TanStack tables).
• Записать приемочные критерии в spec.md для этой эпиковой цели.
• Сгенерировать отчет о изменениях в days-of-progress/frontend-libraries-setup.md с подлинейными темами.

Риски

1. Сложность интеграции MUI с существующими CSS-переменными

Есть шанс конфликта с пользовательскими предопределенными вариантами в src/styles.css. Будет применено архитектурное обрамление: сохраняем оригинальные CSS-переменные, используем CSS-переменные MUI в зонах компонентов и обобщаем значения.

2. Замена авторизации с токенами на Zustand

Реактивность AuthorizationRequest хранилища должна быть очень легкой и не создывать производственную задержку. Константа: успешное восстановление сессии после refresh().

3. Риски старения дока в процессе внедрения

Поскольку этапы реализации совпадают с текущей активной докой эпики (например, frontend-fsd-cleanup), мы подключим эти библиотеки к новому фиче-каталогу frontend-libraries и создадим путь к процессам без длительных пауз.

4. Наложение ограничений на изменение/факты

TypeScript будет строга; мы используем только Partial, Omit в случаях, когда нужно адаптировать старые интерфейсы к новым библиотекам; avoid слишком широких umbrella-типов.

Обучение и интернатура

• Мы будем фильтровать однотипный код из API entities – только хуки.
• Написание «хуковых шаблонов» покрывает весь процесс установки, поддержания и устаревания библиотеки.
• Напишите краткое руководство для команд (можно в apps/docs/docs/frontend/) относительно используемых библиотеки и шаблонов.
• После этапа 5 распределим EP-команде шаги.

Документация по каждому этапу работы

Все этапы будут записаны в days-of-progress/ с кратким содержанием, выводами, проблемами и действиями и реакциями.

Дополнительный фон

Это ветка предназначена для фундаментального автономного этапа работы, отличного от эпики кэширования. Следовательно, мы обратимся к ADR (ADR-016-frontend-infrastructure), чтобы установить порядок и запросить готовность L1 после этапа 5. Цель заключается в превращении состава проекта из UX-driven в FX-driven с быстрыми реакциями.

Контрольный список автора

Все ветки создаются на основе строгих спецификаций. Когда создан баг-трэкер. Контрольный список для управленца:

• Обеспечена совместимость пользователей.
• Написаны тесты.
• Написана архитектурная документация.
• Согласованы стандарты для расширения и подключения после вступления в силу.
• Линтер пройден.
• Превышены ожидаемые тяговые кэши по времени выполнения.
• Серия проверок на ранний этап превзошла цели по дате выпуска.
• Отчет технического директора дан.

Шаблон кода

Существует паттерн для каждого этапа работы. При каждом новом изменении командный разработчик будет:

1. Проверить days-of-progress/ + убедиться, что изменение изменено.
2. Реализовать тест и КТ в src/shared/lib/.
3. Предоставить квази-внешнюю чистку кода (с опросом для удаления непригодных образцов кода).
4. Обновить /docs/features/frontend-libraries/plan.md.
5. Обновить любой артефакт (spec.md, таблицу tasks.md).

Обеспечение отслеживаемости действий и ожидаемых результатов работы над задачей

Каждая задача в изначальном контрольном списке привязана к этапам реализации: выпуск JSON ответов тестирующей команды через CI обязательный в эти фазы перед пуском.

Шаблон рисков комиссара

предвидеть проблемы, ссудить риски и обеспечить безопасность действий; после отслеживания risk-факторов каждая задача возвращается к команде ответственного разработчика (если требуется).

Разработка кода\начало разработки кода\начало разработки кода\начало разработки кода\начало разработки кода

Миграции обладают свойством остановки развития, когда риск команды авторизации достигнут. Поэтому после этапа 3 мы запланируем "миграционный слот".

Заключительный словесный обзор процесса

Имплементация новой инфраструктуры добавит ~3k существующей кодовой базе, увеличив ажурное покрытие и оптимизировав разработку. Сборка будет оставаться быстрой (~1.2s в локальной обработке). Начнем!