Перейти к основному содержимому

Правила Frontend Документации

Назначение​

Документ описывает, как дробить и оформлять документацию frontend приложений Pin: User Platform, Admin Panel и Partner Portal.

Структура Frontend Приложения​

docs/07-frontends/<frontend-app>/
  README.md
  pages/
    <page-slug>/
      page.md
      <page-slug>-<page-component>.md
      forms/
        <form-component>.md
      modals/
        <modal-component>.md
      tables/
        <table-component>.md
  shared-components/
    <shared-component>.md
  widgets/
    <widget>.md
  features/
    <feature>.md
  entities/
    <entity-component>.md
  stores/
    <store>.md
  guards/
    <guard>.md
  api-dependencies/
    <backend-service-or-feature>.md

<frontend-app> — user-platform, admin-panel, partner-portal или другое frontend приложение. <page-slug> соответствует route/экрану в kebab-case: games, play-session, accounting-withdrawals, partner-dashboard.

Где Описывать Страницы И Компоненты​

  • Каждая frontend страница описывается отдельной папкой.
  • Главный файл страницы — pages/<page-slug>/page.md.
  • Page-level компоненты этой страницы описываются рядом в той же папке.
  • Пример: games-game-catalog-content.md, games-filter-sidebar.md, play-session-game-iframe-host.md.
  • Общие компоненты, которые используются несколькими страницами, описываются в shared-components/.
  • FSD-specific компоненты можно описывать в widgets/, features/, entities/.

Шаблон Файла Frontend Страницы​

# <Название Страницы>

## Цель

## Маршрут И Rendering

## Акторы И Guards

## Backend-Зависимости

## Query И Mutation Модели

## Side Effects И Invalidation

## Observability И UI Analytics

## Композиция Компонентов

## Дизайн И Layout

## Состояния Экрана

## Формы, Таблицы И Модальные Окна

## Хранилища Zustand И Client State

## Аналитика И UI-События

## Доступность И i18n

## Ошибки И Edge Cases

## Definition Of Ready

## Definition Of Done

Шаблон Файла Frontend Компонента​

# <ComponentName>

## Назначение

## Где Используется

## Props И Контракты

## Data-Зависимости

## UI Состояния

## Дизайн И Поведение

## Валидация И Ошибки

## Тестовые Сценарии

Правила Страниц​

  • Обзорный файл frontend приложения остается индексом и не хранит всю детализацию страниц.
  • Для каждой route/page создается отдельный pages/<page-slug>/page.md.
  • В каждом файле страницы явно указываются SSR/client rendering, guards, permissions, backend API methods, TanStack Query keys, mutations, Zustand stores и зависимость от SignalR, если она есть.
  • В каждом файле страницы описывается дизайн: сетка, HeroUI компоненты, Tailwind utility groups, responsive поведение, skeleton/empty/error states.
  • DynamicContent является обязательным стандартным контейнером для TanStack Query экранов и компонентов, если состояние загрузки/ошибки не закрыто более специализированным компонентом.
  • Для каждой mutation описываются optimistic update, disabled/loading state, confirmation modal, invalidated query keys, rollback UI и backend error mapping.
  • Для sensitive admin pages описываются audit-visible actions, permission-based visibility и запрет вывода secrets/raw PII.
  • Для страниц с бизнес-критичными действиями описываются UI analytics events, Sentry breadcrumbs, correlationId propagation и user-facing error message policy.

Правила Компонентов​

  • Если компонент принадлежит только одной странице, он документируется внутри папки этой страницы.
  • Если компонент переиспользуется в нескольких страницах, он документируется в shared-components/, widgets/, features/ или entities/ в зависимости от FSD слоя.
  • Для таблиц отдельно описываются columns, filters, sorting, pagination, row actions, bulk actions и permission-based visibility.
  • Для форм отдельно описываются zod schema, field-level validation, backend validation mapping, submit flow и disabled/loading states.
  • Для components, которые отображают state machine, явно описываются допустимые actions для каждого status.
  • Компонентная документация не использует формулировку показать данные; нужно перечислить поля, маскировку, форматирование, empty value и permission visibility.

Definition Of Ready И Done Для Frontend​

  • Frontend задача не готова, если не описаны backend dependencies, contracts, permissions, states, validation, query keys и error mapping.
  • Frontend задача завершена, если UI соответствует backend contract, покрыты loading/error/empty/forbidden states, добавлены tests для guards и critical actions, а документация обновлена.

Обратные ссылки​

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