185 lines
10 KiB
Markdown
185 lines
10 KiB
Markdown
# Документация API
|
||
|
||
VidConf REST + WebSocket API: аутентификация, профиль, динамические конференции, чат, администрирование, health check. Конференции создаются динамически — предустановленных комнат и бронирований нет (см. [ADR-001](../architecture/adr/001-dynamic-conferences-pivot.md)).
|
||
|
||
## Интерактивная документация
|
||
|
||
FastAPI автоматически генерирует интерактивные документы:
|
||
- **Swagger UI:** `http://localhost:8000/docs`
|
||
- **ReDoc:** `http://localhost:8000/redoc`
|
||
- **OpenAPI JSON:** `http://localhost:8000/openapi.json`
|
||
|
||
## Аутентификация & авторизация
|
||
|
||
**[Полная документация: docs/api/auth.md](auth.md)**
|
||
|
||
| Эндпоинт | Метод | Описание |
|
||
|----------|-------|---------|
|
||
| `/api/v1/auth/registration-options` | GET | Публичные опции регистрации (выбор команды) |
|
||
| `/api/v1/auth/register` | POST | Регистрация нового пользователя |
|
||
| `/api/v1/auth/verify-email` | POST | Подтверждение email по токену |
|
||
| `/api/v1/auth/token` | POST | OAuth2 вход (email + пароль) → access + refresh токены |
|
||
| `/api/v1/auth/refresh` | POST | Ротация refresh-токена → новый access-токен |
|
||
| `/api/v1/auth/logout` | POST | Отзыв refresh-токена |
|
||
|
||
## Профиль пользователя
|
||
|
||
**[Полная документация: docs/api/users.md](users.md)**
|
||
|
||
| Эндпоинт | Метод | Описание |
|
||
|----------|-------|---------|
|
||
| `/api/v1/users/me` | GET | Профиль текущего пользователя |
|
||
| `/api/v1/users/me` | PATCH | Обновить ФИО и команду |
|
||
| `/api/v1/users/me/avatar` | POST | Загрузить аватар (JPEG/PNG/WebP, ≤2 МБ) |
|
||
| `/api/v1/users/me/avatar` | DELETE | Удалить аватар |
|
||
| `/api/v1/users` | GET | Поиск пользователей для пикера участников |
|
||
|
||
## Справочник команд
|
||
|
||
**[Полная документация: docs/api/teams.md](teams.md)**
|
||
|
||
| Эндпоинт | Метод | Описание |
|
||
|----------|-------|---------|
|
||
| `/api/v1/teams` | GET | Список всех команд (для выбора в профиле) |
|
||
|
||
**Для CRUD операций над командами см. [Администраторский API](./admin.md#команды).**
|
||
|
||
## LiveKit интеграция
|
||
|
||
| Эндпоинт | Метод | Описание |
|
||
|----------|-------|---------|
|
||
| `/api/v1/livekit/webhook` | POST | Приёмник webhook-событий от LiveKit |
|
||
|
||
## GET /api/health
|
||
|
||
Проверка доступности backend и зависимостей.
|
||
|
||
**Request:**
|
||
```bash
|
||
curl http://localhost:8000/api/health
|
||
```
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"db": true,
|
||
"redis": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Динамические конференции
|
||
|
||
### Управление конференциями
|
||
|
||
**[Полная документация: docs/api/conferences.md](conferences.md)**
|
||
|
||
| Эндпоинт | Метод | Описание |
|
||
|----------|-------|---------|
|
||
| `/api/v1/conferences` | POST | Создать конференцию (мгновенную без scheduled_at или плановую) |
|
||
| `/api/v1/conferences/my` | GET | Мои конференции: закреплённые + предстоящие разовые |
|
||
| `/api/v1/conferences/calendar` | GET | Развёртка вхождений (occurrences) в диапазоне дат (≤62 дней) |
|
||
| `/api/v1/conferences/resolve` | GET | Найти конференцию по номеру или ссылке (публичный, rate limit 10/мин) |
|
||
| `/api/v1/conferences/{id}/join` | POST | Вход зарегистрированного пользователя (с пароль-опцион) |
|
||
| `/api/v1/conferences/{id}/guest-join` | POST | Вход гостем (публичный, rate limit, display_name обязателен) |
|
||
| `/api/v1/conferences/{id}` | PATCH | Изменить конференцию (владелец/администратор) |
|
||
| `/api/v1/conferences/{id}` | DELETE | Удалить конференцию (запрещено для активной) |
|
||
|
||
**Ключевые особенности** (в отличие от прежней модели бронирования переговорных комнат, см. ADR-001):
|
||
- Конференция имеет 9-значный номер (вместо room + booking)
|
||
- Вход по номеру или постоянной ссылке (slug), без привязки к комнате
|
||
- Гости представляются (display_name + email опционально) и участвуют в пайплайне
|
||
- Закреплённые конференции могут повторяться (weekly/biweekly/monthly/every_n_days)
|
||
- Нет конкуренции за ресурсы → EXCLUDE constraint не используется, конфликты — на уровне бизнес-логики
|
||
|
||
---
|
||
|
||
## Администраторский API
|
||
|
||
**[Полная документация: docs/api/admin.md](admin.md)**
|
||
|
||
| Эндпоинт | Метод | Описание |
|
||
|----------|-------|---------|
|
||
| `/api/v1/admin/conferences` | GET | Список всех конференций с фильтрацией и пагинацией (только админ) |
|
||
| `/api/v1/admin/conferences/{id}` | PATCH | Изменить конференцию (только админ) |
|
||
| `/api/v1/admin/conferences/{id}` | DELETE | Удалить конференцию (только админ, запрещено для активной) |
|
||
| `/api/v1/admin/conferences/{id}/invitations` | POST | Поставить рассылку .ics-приглашений (202, асинхронно) |
|
||
| `/api/v1/admin/users` | GET | Список пользователей с пагинацией (только админ) |
|
||
| `/api/v1/admin/users/{id}` | PATCH | Изменить роль/блокировку/команду пользователя (только админ, запрет самоизменения роли/блокировки) |
|
||
| `/api/v1/admin/teams` | GET | Список всех команд (только админ) |
|
||
| `/api/v1/admin/teams` | POST | Создать команду (только админ, 409 при дубле названия) |
|
||
| `/api/v1/admin/teams/{id}` | PATCH | Переименовать команду (только админ) |
|
||
| `/api/v1/admin/teams/{id}` | DELETE | Удалить команду (только админ, у пользователей обнулится team_id) |
|
||
| `/api/v1/admin/settings` | GET | Текущие настройки инстанса (только админ) |
|
||
| `/api/v1/admin/settings` | PUT | Обновить настройки инстанса (только админ; AI-уровень/таймзона/домен регистрации валидируются) |
|
||
|
||
Все эндпоинты требуют JWT токен администратора (403 иначе).
|
||
|
||
---
|
||
|
||
## Чат конференции
|
||
|
||
### Обмен сообщениями в реальном времени
|
||
|
||
**[Полная документация: docs/api/chat.md](chat.md)**
|
||
|
||
| Эндпоинт | Протокол | Описание |
|
||
|----------|----------|---------|
|
||
| `/api/v1/conferences/{id}/chat` | WebSocket | Текстовый чат (auth по LiveKit-токену, история, broadcast через Redis pub/sub) |
|
||
|
||
**Особенности:**
|
||
- Аутентификация на уровне протокола WS (первое сообщение `{"type":"auth","token":<LiveKit-токен>}`)
|
||
- История: последние 50 сообщений открытой сессии конференции
|
||
- Участники: зарегистрированные пользователи + гости (с пометкой `is_guest`)
|
||
- Тоггл `chat.enabled` из настроек инстанса в БД, проверяется на каждом подключении
|
||
- Отправитель видит своё сообщение через pub/sub (echo)
|
||
|
||
**Close-коды:** 4401 (невалидный auth), 4403 (чужая комната), 4404 (чат выключен / конференция не найдена / завершена).
|
||
|
||
**Frontend:** JoinOut содержит `chat_enabled` для отображения/скрытия UI панели без рестарта.
|
||
|
||
---
|
||
|
||
## Планируемый API
|
||
|
||
- Прямой доступ к транскрипту сеанса через API (`GET /api/sessions/{id}/transcript`) — сейчас фразы доступны только внутри пайплайна и итогового саммари, отдельного read-эндпоинта нет.
|
||
|
||
Транскрибация, суммаризация и рассылка саммари/приглашений уже реализованы
|
||
асинхронно через Celery-воркеры (статус — `pipeline_status` в
|
||
`conference_sessions`, см. [workers/README.md](../../workers/README.md)).
|
||
|
||
---
|
||
|
||
## Соглашения
|
||
|
||
**Все timestamps в UTC:**
|
||
```json
|
||
"created_at": "2026-07-15T14:30:00Z"
|
||
```
|
||
|
||
**Авторизация:** JWT Bearer token в заголовке `Authorization` (для защищённых эндпоинтов)
|
||
|
||
**Публичные эндпоинты (без auth):**
|
||
- `GET /api/v1/conferences/resolve` — поиск по номеру/ссылке (rate limit)
|
||
- `POST /api/v1/conferences/{id}/guest-join` — вход гостем (rate limit)
|
||
|
||
**CORS:** Frontend настроен в dev-прокси (vite.config.ts: `/api` → `localhost:8000`)
|
||
|
||
**Плагины:** Конфигурация AI сервисов через `config/plugins.yaml`. См. [docs/plugins/contracts.md](../plugins/contracts.md).
|
||
|
||
---
|
||
|
||
## Тестирование
|
||
|
||
```bash
|
||
# Health check
|
||
curl http://localhost:8000/api/health
|
||
|
||
# Swagger docs
|
||
open http://localhost:8000/docs
|
||
```
|
||
|
||
Полная спецификация — в Swagger UI/ReDoc (см. выше) и в файлах этого каталога.
|