Правила Frontend Разработки

Архитектура

Все frontend приложения используют FSD.
Route-level composition должен быть тонким; бизнес-flow выносится в widgets/features/entities.
Server state хранится в TanStack Query.
Client-only UI state хранится в Zustand.
Route params, query params, forms и provider payloads валидируются Zod.
HeroUI используется как базовая UI система, Tailwind CSS 4 — для layout и композиции.

Элемент	Правило	Пример
Component	PascalCase папка и файл	`LotCard/LotCard.tsx`
Hook	prefix `use`	`useLotCatalogQuery`
Store	`use<Name>Store`	`useAccountingStore`
Query key factory	`<entity>Keys`	`accountingKeys.transactions(filters)`
Schema	`<name>Schema`	`depositFormSchema`
DTO type	`<Name>Dto`	`LotSummaryDto`
View model	`<Name>View`	`AccountingTransactionView`

src/
  app/
  pages/
  widgets/
  features/
  entities/
  shared/
    api/
    config/
    i18n/
    lib/
    ui/
    hooks/

Публичные компоненты, props, типы, хуки и утилиты снабжаются JSDoc (@param, @returns, @template, @default, @example, @deprecated и др.). Поля props/интерфейсов документируются построчными /** … */.
Документируем намерение и инварианты, а не повторяем сигнатуру; на русском, UTF-8.
Сгенерированные shared/api/generated/** руками не трогаем — там JSDoc уже есть.
Полные правила и эталоны: frontend-jsdoc-rules.md.

Ключевые узлы (страницы, формы/модалки, поля, таблицы, строки, действия, диалоги) помечаем data-testid (не id/class) для отладки и автотестов. Поля форм получают маркер автоматически из имени поля; базовые UI-компоненты принимают проп testId.
Полные правила и конвенция имён: frontend-test-markers-rules.md.

DynamicContent обязателен для UI, который отображает TanStack Query state.

Компонент отвечает за:

Server data загружается через TanStack Query hooks или Next.js server components, если нужен SSR.
Query keys создаются typed factories: lotCatalogKeys.list(filters).
Mutations инвалидируют точные query keys и показывают feedback через notification store.
Mutation flow описывает optimistic update, rollback, disabled/loading state, validation mapping и invalidation точных query keys.
Response models валидируются Zod на boundary API adapter-а, если контракт приходит из внешнего/нестабильного источника.

Server components: home, catalog, category pages, provider pages, lot details, SEO metadata, localized static content.
Client components: auth forms, accounting actions, media/map виджеты лота, messages, connections, incentive activation, profile upload, admin tables, partner dashboards.
Server actions не используются для money или внешних provider callbacks. Эти flows идут через backend APIs.

Используют TanStack Router.
Tables поддерживают server-side pagination, sorting, filtering, column visibility, density и export where allowed.
Destructive action требует confirmation modal и permission guard.
Moderation action записывает admin comment, если меняет money, KYC, blocks, withdrawal status, provider status или partner payout status.

Auth и permission guards ставятся на route и feature boundaries.
UI может скрывать запрещенные actions, но backend authorization обязателен.
External input и URL params валидируются Zod.
Frontend отправляет Sentry breadcrumbs для route change, query failure, mutation failure и critical admin action.
API client сохраняет и прокидывает correlationId, если backend вернул его в response headers.
Sensitive values, KYC files, payment реквизиты, tokens и raw PII не попадают в logs, analytics и Sentry.
Critical mutations имеют UI analytics event с operation name, result status и masked entity id.

Автоссылки: где используется этот документ.