541 lines
21 KiB
Markdown
541 lines
21 KiB
Markdown
# API конференций
|
||
|
||
Полная справка по эндпоинтам динамических конференций (см. ADR-001). Конференции создаются мгновенно или планируются; вместо предустановленных комнат и бронирований.
|
||
|
||
## Обзор
|
||
|
||
**Конференции** — это постоянные сущности (номер, ссылка, владелец). Каждый запуск создаёт сеанс (`ConferenceSession`) — единицу AI-пайплайна.
|
||
|
||
- **Номер:** 9 десятичных цифр, уникален, генерируется с retry
|
||
- **Ссылка:** `slug = secrets.token_urlsafe(8)` (11 base64url-символов), URL: `/j/{slug}`
|
||
- **Доступ:** По номеру или ссылке (публичные эндпоинты без auth, rate limit 10/мин)
|
||
- **Гости:** Представляются при входе (имя обязательно, email факультативен для саммари)
|
||
|
||
## Эндпоинты
|
||
|
||
### POST /api/v1/conferences
|
||
|
||
**Создать конференцию.**
|
||
|
||
Без `scheduled_at` → мгновенная (создатель входит сразу); с `scheduled_at` → плановая.
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Request body:**
|
||
```json
|
||
{
|
||
"title": "Встреча Q3",
|
||
"scheduled_at": "2026-07-20T14:00:00Z",
|
||
"duration_minutes": 60,
|
||
"is_pinned": true,
|
||
"recurrence": {
|
||
"type": "weekly",
|
||
"weekdays": [0, 2, 4],
|
||
"time_local": "14:00",
|
||
"timezone": "Europe/Moscow",
|
||
"anchor_date": "2026-07-20",
|
||
"duration_minutes": 60
|
||
},
|
||
"is_closed": false,
|
||
"password": null,
|
||
"summary_recipients": null
|
||
}
|
||
```
|
||
|
||
**Поля:**
|
||
- `title` (str, опционально, ≤255 символов) — название конференции
|
||
- `scheduled_at` (ISO 8601 UTC, опционально) — время запуска; если пусто → мгновенная (status=active)
|
||
- `duration_minutes` (int, опционально, >0) — ожидаемая длительность (не обязывает)
|
||
- `is_pinned` (bool, опционально, default=false) — закреплённая ли (видна в "Моих конференциях")
|
||
- `recurrence` (RecurrenceRule, опционально) — только если is_pinned=true; см. ниже
|
||
- `is_closed` (bool, опционально, default=false) — требуется пароль для входа
|
||
- `password` (str, опционально, ≥4 символа) — обязателен если is_closed=true
|
||
- `summary_recipients` (str, опционально: `'all'`, `'owner'`, или null) — переопределение рассылки саммари конкретной конференции; null = использовать дефолт инстанса
|
||
- `participants` (array, опционально) — список приглашённых; каждый элемент: `{"user_id": "uuid" или null, "email": "string" или null}`. Организатор добавляется автоматически (не требуется в массиве, но если передан — дедуплицируется). Внешние email'ы приглашаются отдельно
|
||
|
||
**RecurrenceRule (JSONB в БД):**
|
||
```json
|
||
{
|
||
"type": "weekly|biweekly|monthly|every_n_days",
|
||
"weekdays": [0, 1, 2, 3, 4, 5, 6],
|
||
"day_of_month": null,
|
||
"interval_days": null,
|
||
"anchor_date": "2026-07-20",
|
||
"time_local": "HH:MM",
|
||
"timezone": "IANA (e.g. Europe/Moscow)",
|
||
"duration_minutes": 60
|
||
}
|
||
```
|
||
|
||
- **weekly:** `weekdays` обязателен (0=пн, 6=вс), список непустой
|
||
- **biweekly:** `weekdays` обязателен, повтор через 2 недели от anchor_date
|
||
- **monthly:** `day_of_month` обязателен (1..31; 31 → последний день короткого месяца)
|
||
- **every_n_days:** `interval_days` обязателен (≥1)
|
||
|
||
**Response (201 Created):**
|
||
```json
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"number": "123456789",
|
||
"slug": "abc123456",
|
||
"title": "Встреча Q3",
|
||
"status": "active|scheduled|ended",
|
||
"is_pinned": true,
|
||
"is_closed": false,
|
||
"scheduled_at": "2026-07-20T14:00:00Z",
|
||
"duration_minutes": 60,
|
||
"recurrence": { /* RecurrenceRule */ },
|
||
"summary_recipients": null,
|
||
"next_occurrence": "2026-07-22T14:00:00Z",
|
||
"created_at": "2026-07-16T12:00:00Z",
|
||
"join": {
|
||
"livekit_url": "wss://livekit.example.com",
|
||
"token": "eyJh...",
|
||
"room_name": "abc123456",
|
||
"conference_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
Мгновенная конференция: `status=active`, `join` заполнено. Плановая: `status=scheduled`, `join=null`.
|
||
|
||
**Коды ошибок:**
|
||
- `422` — `closed_conference_requires_password` (is_closed но нет password)
|
||
- `422` — `recurrence_requires_pinned` (recurrence но is_pinned=false)
|
||
- `422` — `scheduled_at_in_the_past` (дата в прошлом)
|
||
|
||
---
|
||
|
||
### GET /api/v1/conferences/my
|
||
|
||
**Мои конференции: закреплённые + предстоящие разовые владельца ИЛИ приглашённого.**
|
||
|
||
С 2026-07-20 (решение поверх ADR-003) в выдачу попадает конференция, если
|
||
текущий пользователь:
|
||
- владелец (`owner_id == user.id`), **ИЛИ**
|
||
- приглашён по `user_id` (строка `conference_invitees` с `user_id == user.id`), **ИЛИ**
|
||
- приглашён по email (строка `conference_invitees` с `lower(email) == lower(email пользователя)`
|
||
— внешнее приглашение на адрес, под которым человек впоследствии зарегистрировался).
|
||
|
||
Критерии показа не меняются (закреплённая — безусловно; разовая — `status=scheduled`
|
||
и `scheduled_at` в будущем), меняется только круг «чья» конференция. Для
|
||
приглашённого `is_owner=false`, `organizer_name` — имя фактического владельца;
|
||
`participants` не заполняется (как и для владельца — список не раздувает состав).
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Query parameters:** нет
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
[
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"number": "123456789",
|
||
"slug": "abc123456",
|
||
"title": "Встреча Q3",
|
||
"status": "scheduled",
|
||
"is_pinned": true,
|
||
"is_closed": false,
|
||
"scheduled_at": "2026-07-20T14:00:00Z",
|
||
"duration_minutes": 60,
|
||
"recurrence": { /* RecurrenceRule */ },
|
||
"summary_recipients": null,
|
||
"next_occurrence": "2026-07-22T14:00:00Z",
|
||
"created_at": "2026-07-16T12:00:00Z",
|
||
"join": null
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### GET /api/v1/conferences/calendar
|
||
|
||
**Развёртка вхождений (occurrences) конференций в диапазоне дат — владельца ИЛИ приглашённого.**
|
||
|
||
Тот же принцип видимости, что у `GET /conferences/my` (см. выше, решение от
|
||
2026-07-20): вхождения строятся по конференциям, где пользователь владелец
|
||
или приглашён (по `user_id` или по `lower(email)`).
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Query parameters:**
|
||
- `from` (ISO 8601 UTC) — начало диапазона
|
||
- `to` (ISO 8601 UTC) — конец диапазона
|
||
- Максимальная ширина: 62 дня; иначе 422
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
[
|
||
{
|
||
"conference_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"title": "Встреча Q3",
|
||
"starts_at": "2026-07-20T14:00:00Z",
|
||
"ends_at": "2026-07-20T15:00:00Z",
|
||
"number": "123456789",
|
||
"slug": "abc123456",
|
||
"is_pinned": true,
|
||
"is_closed": false
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### GET /api/v1/conferences/resolve
|
||
|
||
**Найти конференцию по номеру или ссылке — публичный эндпоинт без auth.**
|
||
|
||
**Rate limit:** 10 запросов в минуту на IP
|
||
|
||
**Query parameters:**
|
||
- `q` (str, ≥1 символ) — номер (9 цифр) или slug
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"title": "Встреча Q3",
|
||
"status": "active|scheduled|ended",
|
||
"is_closed": false,
|
||
"requires_password": false
|
||
}
|
||
```
|
||
|
||
**Коды ошибок:**
|
||
- `404` — не найдена (живая, мёртвая или несуществующая — единообразный ответ для безопасности)
|
||
- `429` — exceeded rate limit
|
||
|
||
---
|
||
|
||
### POST /api/v1/conferences/{conference_id}/join
|
||
|
||
**Вход зарегистрированного пользователя в конференцию.**
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Path parameters:**
|
||
- `conference_id` (UUID)
|
||
|
||
**Request body:**
|
||
```json
|
||
{
|
||
"password": "optional_password"
|
||
}
|
||
```
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
{
|
||
"livekit_url": "wss://livekit.example.com",
|
||
"token": "eyJh...",
|
||
"room_name": "abc123456",
|
||
"conference_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
```
|
||
|
||
**Коды ошибок:**
|
||
- `404` — conference_not_found
|
||
- `403` — password_required (закрытая конференция без пароля в теле запроса)
|
||
- `403` — invalid_password
|
||
- `410` — conference_ended (статус=ended)
|
||
|
||
---
|
||
|
||
### POST /api/v1/conferences/{conference_id}/guest-join
|
||
|
||
**Вход гостем: представиться (имя обязательно) — публичный, без auth.**
|
||
|
||
**Rate limit:** 10 запросов в минуту на IP
|
||
|
||
**Path parameters:**
|
||
- `conference_id` (UUID)
|
||
|
||
**Request body:**
|
||
```json
|
||
{
|
||
"display_name": "Иван Иванов",
|
||
"email": "ivan@example.com",
|
||
"password": "optional_password"
|
||
}
|
||
```
|
||
|
||
**Поля:**
|
||
- `display_name` (str, 1..255) — обязателен
|
||
- `email` (EmailStr, опционально) — для рассылки саммари
|
||
- `password` (str, опционально) — для закрытых конференций
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
{
|
||
"livekit_url": "wss://livekit.example.com",
|
||
"token": "eyJh...",
|
||
"room_name": "abc123456",
|
||
"conference_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
```
|
||
|
||
**Коды ошибок:**
|
||
- `404` — conference_not_found
|
||
- `403` — password_required
|
||
- `403` — invalid_password
|
||
- `410` — conference_ended
|
||
- `429` — exceeded rate limit
|
||
- `422` — validation_error (display_name пуст, email некорректен)
|
||
|
||
---
|
||
|
||
### PATCH /api/v1/conferences/{conference_id}
|
||
|
||
**Изменить конференцию — только владелец или администратор.**
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Path parameters:**
|
||
- `conference_id` (UUID)
|
||
|
||
**Request body:** все поля опциональны (как ConferenceCreateIn, но PATCH)
|
||
```json
|
||
{
|
||
"title": "Новое название",
|
||
"scheduled_at": "2026-07-25T15:00:00Z",
|
||
"duration_minutes": 90,
|
||
"is_pinned": true,
|
||
"recurrence": null,
|
||
"is_closed": false,
|
||
"password": null
|
||
}
|
||
```
|
||
|
||
**Response (200 OK):** обновленная ConferenceOut
|
||
|
||
**Коды ошибок:**
|
||
- `404` — conference_not_found
|
||
- `403` — not_owner
|
||
- `422` — invalid_conference_state (например, попытка добавить recurrence к неживой конференции)
|
||
|
||
---
|
||
|
||
### DELETE /api/v1/conferences/{conference_id}
|
||
|
||
**Удалить конференцию — только владелец или администратор.**
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Path parameters:**
|
||
- `conference_id` (UUID)
|
||
|
||
**Response (204 No Content)** — без тела
|
||
|
||
**Коды ошибок:**
|
||
- `404` — conference_not_found
|
||
- `403` — not_owner
|
||
- `409` — conference_active (активную конференцию нельзя удалить, дождитесь завершения)
|
||
|
||
---
|
||
|
||
### GET /api/v1/conferences/{conference_id}
|
||
|
||
**Получить детальную информацию о конференции (с полным составом участников) — владелец, администратор ИЛИ приглашённый.**
|
||
|
||
Приглашённый определяется так же, как в `GET /my`/`GET /calendar`: строка
|
||
`conference_invitees` с `user_id == user.id` либо с `lower(email) == lower(email
|
||
пользователя)`. Это расширение касается ТОЛЬКО чтения — `PATCH`/`DELETE`
|
||
по-прежнему разрешены только владельцу или администратору (403 приглашённому).
|
||
|
||
**Требует auth:** JWT Bearer token
|
||
|
||
**Path parameters:**
|
||
- `conference_id` (UUID)
|
||
|
||
**Response (200 OK):**
|
||
```json
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"number": "123456789",
|
||
"slug": "abc123456",
|
||
"title": "Встреча Q3",
|
||
"status": "scheduled",
|
||
"is_pinned": true,
|
||
"is_closed": false,
|
||
"scheduled_at": "2026-07-20T14:00:00Z",
|
||
"duration_minutes": 60,
|
||
"recurrence": { "type": "weekly", "weekdays": [0, 2, 4] },
|
||
"summary_recipients": "all",
|
||
"owner_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"is_owner": true,
|
||
"organizer_name": "Иван Иванов",
|
||
"participants": [
|
||
{
|
||
"user_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"email": "ivan@example.com",
|
||
"name_user": "Иван Иванов",
|
||
"avatar_url": "/media/avatars/550e8400-e29b-41d4-a716-446655440000.jpg"
|
||
},
|
||
{
|
||
"user_id": null,
|
||
"email": "external@example.com",
|
||
"name_user": null,
|
||
"avatar_url": null
|
||
}
|
||
],
|
||
"created_at": "2026-07-16T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
**Поля:**
|
||
- `owner_id` — UUID владельца конференции
|
||
- `is_owner` — true если текущий пользователь владелец
|
||
- `organizer_name` — имя организатора (берётся из `users.name_user`)
|
||
- `participants` — массив приглашённых (зарегистрированные и внешние). **Заполняется только в этом эндпоинте**; в GET /my и /calendar пустой массив.
|
||
|
||
**Коды ошибок:**
|
||
- `404` — conference_not_found
|
||
- `403` — not_owner (пользователь не владелец, не администратор и не приглашён)
|
||
|
||
---
|
||
|
||
## Статусы конференции
|
||
|
||
| Статус | Описание |
|
||
|--------|---------|
|
||
| `scheduled` | Плановая, время ещё не наступило или никто не вошёл |
|
||
| `active` | В настоящий момент идёт (кто-то вошёл или прошло scheduled_at) |
|
||
| `ended` | Завершена; истории, фразы, саммари остаются; вход возвращает 410 |
|
||
|
||
Переходы:
|
||
- Мгновенная создание → `active` сразу
|
||
- Плановая создание → `scheduled`
|
||
- Webhook `room_started` → `active`
|
||
- Webhook `room_finished` → `ended` (если не pinned) или `scheduled` (если pinned)
|
||
- Beat-задача → `ended` если истекло `scheduled_at + duration_minutes` и никто не входил
|
||
|
||
---
|
||
|
||
## LiveKit identity
|
||
|
||
Интеграция с LiveKit на уровне webhook'ов и токенов:
|
||
|
||
- **Зарегистрированный:** `identity = str(user_id)`, `name = user.name_user`
|
||
- **Гость:** `identity = "guest:{guest_access.id}"`, `name = guest_access.display_name`
|
||
|
||
Email гостя в LiveKit не передаётся (PII не утекает участникам).
|
||
|
||
---
|
||
|
||
## Ошибки и коды HTTP
|
||
|
||
| Код | Описание |
|
||
|-----|---------|
|
||
| `200` | OK |
|
||
| `201` | Created (POST конференции) |
|
||
| `204` | No Content (DELETE) |
|
||
| `400` | Bad Request (некорректный JSON) |
|
||
| `401` | Unauthorized (JWT missing или invalid) |
|
||
| `403` | Forbidden (password_required, invalid_password, not_owner) |
|
||
| `404` | Not Found (конференция не существует или не найдена) |
|
||
| `409` | Conflict (conference_active — нельзя удалить активную) |
|
||
| `410` | Gone (conference_ended — вход в завершённую) |
|
||
| `422` | Unprocessable Entity (валидация, invalid range на /calendar) |
|
||
| `429` | Too Many Requests (rate limit на /resolve, /guest-join) |
|
||
|
||
---
|
||
|
||
## Примеры запросов
|
||
|
||
### Создать мгновенную конференцию
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/conferences \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"title":"Quick call"}'
|
||
```
|
||
|
||
### Создать плановую с повторением (еженедельно по пн/ср/пт)
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/conferences \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title": "Q3 standup",
|
||
"scheduled_at": "2026-07-21T09:00:00Z",
|
||
"duration_minutes": 30,
|
||
"is_pinned": true,
|
||
"is_closed": true,
|
||
"password": "secret123",
|
||
"recurrence": {
|
||
"type": "weekly",
|
||
"weekdays": [0, 2, 4],
|
||
"time_local": "09:00",
|
||
"timezone": "Europe/Moscow",
|
||
"anchor_date": "2026-07-21",
|
||
"duration_minutes": 30
|
||
}
|
||
}'
|
||
```
|
||
|
||
### Вход по номеру (публичный, без auth)
|
||
```bash
|
||
curl http://localhost:8000/api/v1/conferences/resolve?q=123456789
|
||
```
|
||
|
||
### Вход гостем
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/conferences/550e8400-e29b-41d4-a716-446655440000/guest-join \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"display_name": "Иван",
|
||
"email": "ivan@example.com",
|
||
"password": "secret123"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## Рассылка приглашений
|
||
|
||
При создании (POST) или изменении (PATCH) конференции отправляются .ics-приглашения:
|
||
|
||
**Получатели:**
|
||
- Организатор (владелец конференции, автоматически)
|
||
- Все приглашённые в `participants` (зарегистрированные пользователи и внешние email'ы)
|
||
|
||
**Содержимое письма:**
|
||
- Тема: `"Приглашение: <название конференции>"`
|
||
- Вложение `.ics` (iCalendar формат)
|
||
- `METHOD:REQUEST` — приглашение
|
||
- `VTIMEZONE` — часовой пояс инстанса (для корректного отображения)
|
||
- `RRULE` — правило повтора (для закреплённых конференций с `recurrence`)
|
||
- `SEQUENCE` — номер версии события
|
||
|
||
**Логика рассылки:**
|
||
- **Создание (POST):** Рассылка всем в `participants` и организатору. `SEQUENCE=0`.
|
||
- **Изменение расписания (PATCH `scheduled_at`, `duration_minutes`, `recurrence`, `title`):** Инкрементируется `SEQUENCE`, рассылка повторяется.
|
||
- **Изменение только состава участников (PATCH `participants`):** Рассылка отправляется, но `SEQUENCE` **не меняется** (календарные клиенты игнорируют обновления с неизменённым SEQUENCE).
|
||
- **Прочие изменения (пароль, `is_closed`, `summary_recipients`):** Рассылка **не отправляется**.
|
||
|
||
**Внешние приглашённые:**
|
||
- Письма отправляются на email'ы без требования аутентификации.
|
||
- При входе по ссылке гост вводит имя и опционально email.
|
||
- Если email гостя совпадает с приглашённым — он может получить саммари (зависит от `summary_recipients`).
|
||
|
||
---
|
||
|
||
## Примечания
|
||
|
||
- Все `datetime` сохраняются и возвращаются в UTC (ISO 8601, суффикс `Z`)
|
||
- Преобразование в локальное время — на клиенте по таймзоне браузера
|
||
- `.ics` экспорт включает `VTIMEZONE` для правильной конвертации (`services/ics.py`)
|
||
- Номер и slug неизменны всю жизнь конференции и не переиспользуются
|
||
- `recurrence` хранится как JSONB (можно запросить всё, развёртка только в памяти)
|
||
|
||
---
|
||
|
||
## Ссылки
|
||
|
||
- [Architecture Overview](../architecture/README.md) — система компонентов
|
||
- [Database Schema](../db/schema.md) — таблицы `conferences`, `conference_sessions`, `guest_access`
|
||
- [ADR-001: Динамические конференции вместо бронирований](../architecture/adr/001-dynamic-conferences-pivot.md) — обоснование решения
|
||
- [Recurrence Service](../../backend/services/recurrence.py) — реализация развёртки
|