182 lines
8.9 KiB
Markdown
182 lines
8.9 KiB
Markdown
# HTTP API
|
||
|
||
Этот документ описывает текущий HTTP API EUSRR. Полный список операций и схем ответов генерируется из кода; вручную поддерживаемый список endpoint-ов здесь намеренно не дублируется.
|
||
|
||
## Источники истины
|
||
|
||
- URL верхнего уровня: `backend/api/urls.py`
|
||
- API v1: `backend/api/v1/urls.py`
|
||
- authentication: `backend/api/auth/`
|
||
- OpenAPI tags и metadata: `backend/api/schema.py`
|
||
- frontend transport: `frontend/src/lib/api/client.ts`
|
||
- доменные frontend clients: `frontend/src/lib/api/`
|
||
- проверка документации: `backend/tests/api/test_documentation.py`
|
||
|
||
Если этот guide расходится с `/api/schema/`, верной считается OpenAPI-схема.
|
||
|
||
## Локальный запуск
|
||
|
||
Backend запускается как ASGI-приложение. Один процесс обслуживает HTTP и WebSocket:
|
||
|
||
```bash
|
||
cd backend
|
||
python manage.py migrate
|
||
daphne -b 0.0.0.0 -p 8000 eusrr_backend.asgi:application
|
||
```
|
||
|
||
Frontend:
|
||
|
||
```bash
|
||
cd frontend
|
||
cp .env.example .env.local
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Для стандартной локальной конфигурации:
|
||
|
||
```dotenv
|
||
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
|
||
NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws/
|
||
```
|
||
|
||
## Документация, доступная из приложения
|
||
|
||
| URL | Назначение |
|
||
| --- | --- |
|
||
| `/api/schema/` | OpenAPI 3 schema |
|
||
| `/api/docs/` | Swagger UI |
|
||
| `/api/redoc/` | ReDoc |
|
||
| `/api/ws/schema/` | AsyncAPI schema для `/ws/` |
|
||
| `/api/ws/docs/` | HTML-страница WebSocket API |
|
||
|
||
Эти страницы доступны без аутентификации. Бизнес-endpoint-ы по умолчанию требуют авторизованного пользователя и Django model permissions.
|
||
|
||
## Пространства URL
|
||
|
||
| Prefix | Содержимое |
|
||
| --- | --- |
|
||
| `/api/auth/` | JWT, QR login, регистрация, password reset, auth-сессии |
|
||
| `/api/v1/` | Основной versioned REST API |
|
||
| `/api/v1/auth/` | Совместимый alias authentication API |
|
||
| `/api/v1/communications/` | Чаты, сообщения и опросы |
|
||
| `/api/v1/notifications/` | Уведомления, preferences и Web Push |
|
||
| `/api/v1/schedule/` | Календари, события, правила, occurrences и relations |
|
||
| `/api/v1/procurement/` | Закупки и оборудование |
|
||
| `/api/v1/finance/` | Финансы и payroll |
|
||
| `/api/v1/tasks/` | Задачи, доски и automation |
|
||
|
||
Версии `/api/v2/` в текущем проекте нет. Не добавляйте ссылки на неё и не используйте старые `VITE_API_URL`/Vite-примеры: frontend построен на Next.js.
|
||
|
||
## Аутентификация
|
||
|
||
Основной способ — JWT:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/auth/token/ \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"email":"user@example.com","password":"change-me"}'
|
||
```
|
||
|
||
Вместо `email` можно передать `phone` или `phone_number`. Успешный ответ содержит `access` и `refresh`.
|
||
|
||
Защищённый запрос:
|
||
|
||
```bash
|
||
curl http://localhost:8000/api/v1/employees/me/ \
|
||
-H 'Authorization: Bearer ACCESS_TOKEN'
|
||
```
|
||
|
||
Обновление access token:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/auth/token/refresh/ \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"refresh":"REFRESH_TOKEN"}'
|
||
```
|
||
|
||
Каждая пара токенов привязана к записи `UserAuthSession` через claim `session_id`. Удалённая или отозванная сессия инвалидирует и HTTP, и WebSocket-доступ. Управление сессиями:
|
||
|
||
- `GET /api/auth/sessions/`
|
||
- `DELETE /api/auth/sessions/{session_id}/`
|
||
- `POST /api/auth/sessions/logout-others/`
|
||
|
||
Frontend хранит access/refresh token в `localStorage`, добавляет Bearer header, выполняет единичный refresh при `401` и повторяет исходный запрос. Ошибка refresh очищает локальную сессию.
|
||
|
||
## Формат запросов и ответов
|
||
|
||
- JSON используется по умолчанию.
|
||
- Для загрузки файлов передавайте `FormData`; API client не устанавливает `Content-Type` вручную, чтобы браузер добавил multipart boundary.
|
||
- Стандартная пагинация: `page` и `page_size`, значение по умолчанию — 20.
|
||
- Максимальный `page_size`, принятый базовым paginator, — 10000. Для UI используйте существенно меньшие страницы.
|
||
- `204 No Content` не содержит JSON-тело.
|
||
- `401` означает отсутствующую, истёкшую или отозванную auth-сессию.
|
||
- `403` означает, что пользователь распознан, но не имеет требуемого model/object permission.
|
||
- `400` обычно содержит field-level validation errors; не преобразуйте его в общий `500` на frontend.
|
||
|
||
## Frontend proxy
|
||
|
||
Browser вызывает относительные пути `/api/...`. Next.js route `frontend/src/app/api/[...path]/route.ts` проксирует их на `${NEXT_PUBLIC_BACKEND_URL}/api/...` и сохраняет query string, authorization headers, multipart body и streaming GET responses.
|
||
|
||
Используйте собранный client:
|
||
|
||
```ts
|
||
import { apiClient } from "@/lib/api";
|
||
|
||
const currentUser = await apiClient.getCurrentUser();
|
||
```
|
||
|
||
Новый доменный API добавляется отдельным модулем в `frontend/src/lib/api/` и подключается в `frontend/src/lib/api/index.ts`. Не создавайте второй fetch-wrapper и не встраивайте абсолютный backend URL в компоненты.
|
||
|
||
## Communications API
|
||
|
||
Router публикует:
|
||
|
||
- `communications/chats`
|
||
- `communications/messages`
|
||
- `communications/polls`
|
||
|
||
Кроме CRUD доступны actions для участников, ролей, поиска, истории, отметки прочитанного, загрузок, реакций, пересылки, bulk delete и голосований. Их точные URL и payload смотрите в Swagger: они формируются из `backend/communications/api/viewsets.py`.
|
||
|
||
Для отметки прочитанного используйте HTTP action:
|
||
|
||
```text
|
||
POST /api/v1/communications/chats/{chat_id}/mark-read/
|
||
```
|
||
|
||
WebSocket action `mark_read` оставлен только как deprecated compatibility path и не выполняет запись.
|
||
|
||
## Добавление endpoint-а
|
||
|
||
1. Добавьте serializer, permissions и view/viewset в доменный модуль.
|
||
2. Зарегистрируйте URL под `/api/v1/`; unversioned бизнес-URL не добавляются.
|
||
3. Добавьте `extend_schema` там, где drf-spectacular не может вывести контракт автоматически.
|
||
4. Проверьте, что object permissions фильтруют и list, и detail queryset.
|
||
5. Добавьте backend tests для успешного запроса, `401`, `403`, validation и ownership boundaries.
|
||
6. Добавьте или расширьте доменный frontend client.
|
||
7. Убедитесь, что endpoint появился в `/api/schema/` с правильным tag.
|
||
|
||
## Проверка
|
||
|
||
```bash
|
||
cd backend
|
||
pytest tests/api/test_documentation.py tests/api/auth tests/api/v1
|
||
```
|
||
|
||
Точечные suites предпочтительнее ручной коллекции curl-команд. Для диагностики контракта:
|
||
|
||
```bash
|
||
curl -fsS http://localhost:8000/api/schema/ -H 'Accept: application/json'
|
||
```
|
||
|
||
При изменении WebSocket-протокола дополнительно обновите `backend/docs/architecture/websocket-asyncapi.yaml` и выполните realtime tests.
|
||
|
||
## Типовые ошибки
|
||
|
||
- `404` на `/api/v2/...`: такой версии нет; используйте `/api/v1/...`.
|
||
- `401` после успешного login: проверьте, что отправляется access token, а auth-сессия не отозвана.
|
||
- Повторяющиеся refresh-запросы: используйте общий `apiClient`, в нём refresh уже сериализован.
|
||
- CORS в локальной разработке: browser должен обращаться к Next.js `/api/...`; прямой backend-доступ разрешён только origin-ам из `CORS_ALLOWED_ORIGINS`.
|
||
- Ошибка загрузки файла: не задавайте multipart `Content-Type` вручную.
|
||
|