# React, Next.js и генерируемые клиенты TypeScript

Elang — серверная часть на PHP. Его официальный сайт документации остаётся на HTML, формируемом сервером, CSS и обычном JavaScript. Интерфейс вашего приложения может использовать React, Next.js, другой JavaScript-фреймворк, мобильный код или серверный клиент.

## Создание полного проекта с интерфейсом и сервером

Устанавливайте версии React и Next.js для разработки непосредственно из Packagist. Проверены установка обоих PHP-приложений, зависимости, doctor и тесты API. Пакеты остаются предварительными версиями для разработки, а не стабильными выпусками.

```bash
composer create-project elang/react my-react-app dev-main
# Alternatively:
composer create-project elang/next my-next-app dev-main
```

Настроенный глобальный установщик также принимает `elang new my-app --starter=react` или `--starter=next`. Composer подготавливает PHP-приложение. Исходный код интерфейса находится в `frontend/`; вручную скачивать ZIP не нужно. Требования: PHP 8.3+, Composer 2 и Node 22.12+ для этих стартовых проектов интерфейса.

```bash
cd my-react-app
php elang serve
```

Во втором терминале:

```bash
cd my-react-app/frontend
npm ci
npm run dev
```

Откройте URL интерфейса, выведенный Vite или Next. Оставьте серверную часть работающей по выведенному ею адресу. При изменении адреса серверной части скопируйте `frontend/.env.example` в описанный документацией локальный файл окружения интерфейса. `ELANG_BACKEND_URL` — серверная конфигурация прокси; она никогда не должна содержать секреты, открытые браузеру.

## Как работает аутентификация

Оба стартовых проекта используют прокси `/api` на том же источнике. Браузер хранит cookie сессии HttpOnly; bearer-токены не сохраняются в localStorage. `GET /api/session` возвращает текущего пользователя, токен CSRF, доступность регистрации, доступность почты и признак ожидания второго фактора. Небезопасные запросы включают `X-CSRF-Token`.

1. Загрузите сессию перед отправкой формы.
2. Зарегистрируйтесь или войдите через `/api/session/register` или `/api/session/login`.
3. Если `mfaRequired` равен true, отправьте код в `/api/session/mfa`; доступ к учётной записи остаётся ожидающим до успешного завершения.
4. Обновляйте состояние сессии после записи, поскольку вход и выход меняют сессию и токен CSRF.
5. Создавайте, изменяйте, просматривайте и удаляйте свои закрытые заметки.

Новые учётные записи должны подтвердить почту перед защищёнными операциями записи API. При локальной разработке откройте `/_elang/studio/mail` серверной части, чтобы просмотреть зашифрованный почтовый ящик разработки. Область действия cookie определяется хостом или доменом и путём, а не портом; использование разных имён хостов интерфейса и серверной части может потребовать отдельного входа в серверную часть. Страница `/backend-account` стартового проекта объясняет этот переход.

## Границы прокси

Прокси Next перенаправляет только явно разрешённые пути и методы API, ограничивает JSON-запросы 32 КиБ, использует ограниченный тайм-аут, отклоняет перенаправления от вышестоящего сервера и передаёт отдельные заголовки Set-Cookie. Небезопасные запросы браузера должны поступать с собственного источника интерфейса. Перед межсерверным запросом прокси удаляет браузерный Origin, чтобы серверная часть не путала трафик прокси с прямым запросом CORS.

Прокси разработки Vite применяет проверку совпадения источника для небезопасных вызовов. В рабочей среде развёртывайте проверенный обратный прокси или прокси приложения; сервер разработки Vite не является рабочим развёртыванием. Никогда не открывайте универсальный параметр URL вышестоящего сервера, не перенаправляйте произвольную браузерную авторизацию на посторонние хосты и не отключайте CSRF ради работы прокси.

Для браузера, напрямую обращающегося к другому источнику API, настройте явные источники CORS и проверенную политику учётных данных и cookie. CORS не является аутентификацией. Предоставленные стартовые проекты избегают межсайтовых cookie с помощью прокси на одном источнике. Серверные и мобильные клиенты могут вместо этого использовать bearer-токены с областями доступа.

## Генерация контракта TypeScript

Стартовый проект Notes публикует `/openapi.json` из `resources/openapi.php`. Сгенерируйте отдельный типизированный клиент из этой доверенной локальной схемы:

```bash
php elang api:types --schema=resources/openapi.php --output=frontend/src/lib/generated.ts
# Next.js starter:
php elang api:types --schema=resources/openapi.php --output=frontend/lib/generated.ts
```

Сгенерированный модуль содержит типы схемы, входные и выходные данные операций, маршруты и `createApiClient()`. Стартовый проект импортирует эти типы и использует сгенерированные операции для записи заметок. При изменении контракта серверной части отредактируйте документ OpenAPI, повторите генерацию, проверьте типы и просмотрите полученные изменения.

```ts
import { createApiClient } from './generated.ts';

const api = createApiClient();
const result = await api.request('createNote', {
  body: { title: 'First idea', body: 'A useful note' },
  headers: { 'X-CSRF-Token': csrfToken },
});
```

Генератор намеренно поддерживает ограниченное подмножество OpenAPI 3.1: локальные ссылки на компоненты, объекты, массивы, скалярные типы и null, перечисления, объединения, тела запросов JSON и схемы ответов JSON/SSE. Неподдерживаемые конструкции схемы явно приводят к ошибке. Типы TypeScript не проверяют недоверенный JSON во время выполнения. Операции SSE описывают контракт; для живого потока используйте EventSource или потоковую обработку вместо вспомогательного вызова, ориентированного на JSON.

## Проверка и развёртывание

```bash
cd frontend
npm run typecheck
npm test
npm run build
```

Next также предоставляет `npm run test:proxy`. Запустите набор тестов PHP и браузерный сценарий с реальной серверной частью: войдите, подтвердите адрес, завершите MFA, если она включена, создайте, измените и удалите данные, обновите страницу, выйдите и попытайтесь прочитать данные другого пользователя. Проверьте CSP, HTTPS, доверенные заголовки прокси, конфигурацию URL серверной части, домен cookie, тайм-ауты и доступность вышестоящего сервера в своём развёртывании.

Файлы фиксации зависимостей интерфейса закрепляют проверенное дерево зависимостей. Обновления безопасности по-прежнему требуют проверки и повторной валидации. См. [аутентификацию API](/docs/v0.1/authentication), [безопасность учётной записи](/docs/v0.1/account-security) и [тестирование](/docs/v0.1/testing).