refactor: align frontend with FSD architecture

docs/generated-api.md

@@ -0,0 +1,82 @@
+# Generated API
+
+Дата актуализации: 2026-06-22
+
+## Назначение
+
+Проект использует Orval для генерации TypeScript API-клиентов и Zod-моделей из `openapi.json`.
+Generated-код не редактируется вручную.
+
+## Команда генерации
+
+```bash
+bun run apigen
+```
+
+Orval config находится в `orval.config.ts`.
+
+## Входной файл
+
+```text
+openapi.json
+```
+
+В config есть нормализация русскоязычных тегов OpenAPI в стабильные англоязычные имена файлов:
+
+- `Аутентификация` -> `authentication`
+- `Карта компетенций: аналитика` -> `competence-map-analytics`
+- `Мониторинг` -> `monitoring`
+- `Пользователь` -> `user`
+- `Управление пользователями` -> `user-management`
+
+Config также умеет читать первый валидный JSON-документ, если исходный OpenAPI-файл содержит
+лишние данные после первого JSON.
+
+## Выходные директории
+
+```text
+src/shared/api/generated-api/
+src/shared/model/generated-zod/
+```
+
+`generated-api` использует custom mutator:
+
+```text
+src/shared/api/axiosInstance.ts
+```
+
+Это сохраняет единое поведение API-клиента: base URL, credentials, refresh flow, error handling
+и abort signal.
+
+## Public facade
+
+Прикладной код не должен импортировать generated-файлы напрямую. Правильный путь:
+
+```ts
+import { getCompetenceMapAnalytics, type Login } from '@/shared/api'
+```
+
+Неправильный путь:
+
+```ts
+import { api_v1_competence_map_analytics_list } from '@/shared/api/generated-api/competence-map-analytics'
+```
+
+Facade `src/shared/api/index.ts` сейчас экспортирует только используемые приложением endpoint
+functions, token primitives, error helpers и DTO-типы.
+
+## Правила изменений
+
+- Не редактировать файлы в `generated-api` и `generated-zod` вручную.
+- При изменении backend контракта обновить `openapi.json` и выполнить `bun run apigen`.
+- После генерации выполнить `bun run check:full`.
+- Если новому экрану нужен endpoint, сначала добавить осознанный export в `src/shared/api/index.ts`
+  или отдельный wrapper, а не импортировать generated-файл напрямую.
+- Если DTO требует page-specific адаптации, mapper должен жить рядом с owner-страницей или рядом
+  с API wrapper, а не в generated-зоне.
+
+## Tooling exclusions
+
+Generated-директории исключены из Steiger и Prettier через `steiger.config.ts` и `.prettierignore`.
+Это не разрешение писать ручной код внутри generated-зон. Исключение нужно только для стабильной
+работы tooling после Orval generation.