Назначение

Feature <FeatureName> в <frontend app> реализует пользовательское действие <краткое описание>.

Metadata

Поле	Значение
App	<pin-admin/...>
FSD Layer	features/<feature-slug>
Слой влияния	UI + API mutation / query
Файл	src/features/<feature-slug>/
Статус	draft / approved / deprecated
Реализуемая user story	<UC-XX-YY>

Контекст

Поле	Значение
Где используется	<список widgets/pages>
Триггер	<кнопка / shortcut / автоматическая>
Целевой actor	<TenantAdministrator/FacilityManager/Employee/PlatformAdministrator>
Permission	<требуемая роль или RoleGrant>

Связанные API Endpoints

Метод	Путь	Назначение
POST	/api/...	<command>
GET	/api/...	<query для предварительной загрузки>

Состав Слайса

src/features/<feature-slug>/
  ui/
    <FeatureName>.tsx          // главный компонент feature
    <FeatureName>Dialog.tsx    // диалог (если применимо)
    <FeatureName>Form.tsx      // форма (если применимо)
  api/
    api.ts                      // обёртки над Axios
  model/
    schema.ts                   // Zod schema запроса
    use-<feature>-mutation.ts   // TanStack mutation hook
    use-<feature>-query.ts      // TanStack query hook
  lib/
    error-mapping.ts            // server code → field path
  index.ts                      // public API

Контракты Mutation / Query

Mutation <MutationName>

Поле	Значение
Endpoint	POST /api/...
Request schema	<schema>
Response model	<model>
Optimistic update	да / нет (правило отката)
Invalidated query keys	<keys>
Confirmation modal	да / нет (когда)
Disabled / loading state	<правило>
Backend error mapping	<code -> поле формы>

Query <QueryName> (если применимо)

Поле	Значение
Endpoint	GET /api/...
Query key	<keys>
Staleness	<staleTime>
Refetch на focus	да / нет

UI Flow

1. <шаг> — <описание>.
2. <шаг> — <описание>.
3. <шаг> — <описание>.

Состояния

State	Триггер	UI	Доступ
Idle	—	<кнопка>	Доступна по permission
Loading	submit	spinner + disabled	Disable
Success	2xx response	Toast + invalidate + close	—
Validation Error	422	Form errors mapping	Кнопка снова active
Forbidden	403	Forbidden modal	—
Conflict	409 ROW_VERSION_CONFLICT	Refetch + warning	Reset form
Server Error	5xx	Toast + retry button	Кнопка снова active

Формы (если применимо)

• Zod schema: <schema>.
• TanStack Form: useForm({ defaultValues, validators }).
• Field-level validation: <правила>.
• Server validation mapping: <error.code -> field>.
• Sensitive fields: <none/list>.
• Unsaved changes behavior: <блокировка навигации / confirm>.

Permissions

Действие	Permission
Видеть triggering элемент	<View access на ресурс>
Выполнить mutation	<Edit / Delete access>

Side Effects

• Domain events: какие backend события могут возникнуть.
• Kafka events: какие Kafka события возникают.
• Audit: что попадает в AuditEvents.
• Locale strings: ключи i18n.
• Analytics: какие frontend события публикуются.

Тестирование

#	Сценарий	Что проверяется
1	Successful flow	2xx → optimistic + invalidation + close
2	Validation error mapping	422 → field-level errors
3	Forbidden	403 → guard message
4	Conflict	409 → refetch + warning
5	Permission guard	Скрыто без permission
6	Mobile responsive	Корректно на 320–1920+
7	Keyboard accessibility	Полный обход с клавиатуры

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

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

• index.md (1): Шаблоны Документации

Связанные Документы

• Backend API: docs/03-domain/Pin/03-modules/<module>/api/<endpoint>.md.
• Backend Command: docs/03-domain/Pin/03-modules/<module>/commands/<command>.md.
• Use Case: docs/03-domain/Pin/03-modules/<module>/use-cases/<uc>.md.
• Frontend page: docs/04-frontends/<app>/03-pages/<page>.md.
• Зависимые entities: docs/04-frontends/<app>/06-entities/<entity>/.