docs: refine frontend conventions and routing

2026-09-15 05:42:14 +03:00
parent 0244acf429
commit 718365cd5a
10 changed files with 202 additions and 134 deletions
@@ -0,0 +1,34 @@
+# Frontend mental model
+
+React + TypeScript + Vite SPA. Router задаёт navigation; providers в `app`
+подключают auth, TanStack Query, i18n и Mantine. Vite использует React Compiler;
+Vitest — отдельную JSDOM конфигурацию. Точные versions/scripts — в
+[package.json](../package.json), реализация — source of truth.
+
+```text
+app → pages → features → entities → shared
+page container → page VM → entity/feature query → shared/api → backend /api/v1
+                         ↓
+                 props → state/section views
+```
+
+`widgets` не используется. Pages владеют route composition и локальным поведением;
+features — самостоятельными возможностями пользователя; entities — устойчивыми
+доменными понятиями; shared — техническими primitives без domain responsibility.
+Правила выделения owner и public `index.ts` — в
+[FSD convention](conventions/frontend-architecture.md).
+
+Server state и lifecycle запроса принадлежат TanStack Query; VM собирает данные
+для view. Transport — `openapi-fetch`/`openapi-react-query`, типизированные из
+предоставленного snapshot через `openapi-typescript`. Backend владеет wire
+contract; frontend не читает его checkout для генерации и не вызывает T-Bank.
+[Data convention](conventions/frontend-data.md) задаёт auth/cache границы.
+
+`shared/theme/tokens.json` — переносимый source design tokens; `theme.ts`
+адаптирует доверенный JSON к Mantine без runtime schema. App и Storybook читают
+public API `shared/theme`. Storybook показывает synthetic presentation states,
+не использует application API. RTL/MSW проверяют поведение приложения отдельно.
+
+Existing route-aware AppShell расположен в shared/ui; это legacy placement,
+а не образец нового shared primitive. Общий план улучшений читается только
+при migration через [router](CONVENTIONS.md).