From 203b7cbf208d5cadd7ff694ff432debf2aa765e5 Mon Sep 17 00:00:00 2001
From: Sergey Krylov <ksv741@mail.ru>
Date: Tue, 23 Jun 2026 06:04:25 +0300
Subject: [PATCH] docs: add spec for frontend infrastructure tooling

---
 .../frontend-infrastructure-tooling/spec.md   | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/features/frontend-infrastructure-tooling/spec.md

diff --git a/docs/features/frontend-infrastructure-tooling/spec.md b/docs/features/frontend-infrastructure-tooling/spec.md
new file mode 100644
index 0000000..b32bb8e
--- /dev/null
+++ b/docs/features/frontend-infrastructure-tooling/spec.md
@@ -0,0 +1,87 @@
+# Frontend Infrastructure Tooling
+
+## Purpose
+
+Модернизировать инструментарий и инфраструктуру фронтенда: ускорить разработку, улучшить типобезопасность, убрать дублирование, дать возможность разрабатывать UI без запущенного бэкенда.
+
+## Requirements
+
+### 1. MSW Browser Mode
+
+Фронтенд должен иметь возможность запускаться без бэкенда при `VITE_API_MOCK=true`.
+
+- Создать browser entry для MSW (shared/lib/test/browser.ts с setupWorker)
+- Развернуть mockServiceWorker.js в public/
+- Переиспользовать существующие MSW handlers (shared/lib/test/handlers.ts) — не дублировать
+- При VITE_API_MOCK=true в dev-режиме все API-запросы перехватываются MSW
+- При VITE_API_MOCK=false или отсутствии — поведение не меняется (запросы идут в реальный API)
+
+### 2. Biome вместо ESLint + Prettier
+
+Заменить ESLint 8 + Prettier на Biome как единый инструмент линтинга и форматирования.
+
+- Удалить .eslintrc.cjs, зависимости eslint, prettier
+- Установить @biomejs/biome с конфигом biome.json
+- Перенести существующие правила ESLint (no-unused-vars, no-restricted-imports, FSD layer boundaries)
+- Заменить npm-скрипт lint на biome check
+- Обновить pre-commit hook и CI
+- Если FSD-правила @conarti/feature-sliced не переносятся в Biome — оставить минимальный ESLint только для них
+
+### 3. Унификация типов API
+
+Убрать дублирование рукописных и сгенерированных типов.
+
+- Удалить рукописный shared/api/responses.ts
+- Перенести все entity-API файлы на типы из shared/api/types.ts (openapi-typescript)
+- normalizeEnvelope перенести в kyClient.ts
+- Типы пишем только через codegen, рукописные — удаляем
+
+### 4. Полная миграция на ky
+
+Заменить нативный fetch на ky во всех API-вызовах.
+
+- Доработать kyClient.ts: добавить normalizeEnvelope в afterResponse hook
+- Перевести все entity-API файлы с request() на kyApi
+- Удалить shared/api/client.ts
+- Заменить configureAuth на configureKyAuth в точке входа
+
+### 5. TanStack Router + Lazy Loading
+
+Мигрировать с react-router-dom на TanStack Router.
+
+- Установить @tanstack/react-router, @tanstack/router-devtools, @tanstack/router-plugin
+- Создать файловую структуру роутов (Route Tree generation)
+- Все страницы lazy по умолчанию (built-in, без React.lazy)
+- Search params с Zod-схемами для страниц с фильтрацией (screener, broker-operations)
+- ProtectedRoute реализовать через beforeLoad guard
+- AppLayout — как layout route (__root.tsx)
+- Loaders для предзагрузки данных с TanStack Query в ключевых роутах
+- Заменить все импорты react-router-dom на @tanstack/react-router
+
+### 6. Валидация окружения
+
+Создать формальную Zod-схему для VITE_* переменных с проверкой при старте.
+
+- Определить ожидаемые VITE_* переменные с их типами
+- Валидировать при старте приложения в main.tsx или App.tsx
+- При отсутствии обязательных переменных — понятная ошибка в консоли/браузере
+
+## Acceptance Criteria
+
+| # | Acceptance Criteria | Verification |
+|---|-------------------|--------------|
+| 1 | `npm run dev VITE_API_MOCK=true` работает без бэкенда | Ручная проверка |
+| 2 | `biome check src/` проходит без ошибок | `biome check` |
+| 3 | Все тесты проходят | `npm run test` |
+| 4 | `npm run build` проходит | `npm run build` |
+| 5 | Нет рукописных типов API в shared/api/responses.ts | grep на импорты |
+| 6 | Все API-запросы идут через ky | grep на fetch в entity API |
+| 7 | Роуты лениво загружаются | DevTools Network tab |
+| 8 | При невалидных VITE_* — ошибка при старте | Ручная проверка |
+
+## Out of Scope
+
+- Автоматизация codegen в dev/watch mode
+- Storybook
+- E2E-тесты (Playwright)
+- Миграция с React 18 на React 19