# 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.