# Backend — FastAPI приложение

HTTP API сервер для VidConf: аутентификация (JWT), динамические конференции
(создание, календарь, вход по ссылке/номеру, гостевой доступ), чат в
реальном времени, администрирование (конференции/пользователи/команды/
настройки инстанса), контракты плагинов (Transcriber/Summarizer) и интеграция
с LiveKit (токены, webhook-приёмник).

## Структура

```
backend/
├── api/                    HTTP endpoint'ы
│   ├── __init__.py
│   ├── deps.py            JWT-зависимости для аутентификации
│   ├── auth.py            Регистрация, подтверждение email, вход, refresh, выход
│   ├── users.py           Профиль, аватары, поиск пользователей (GET/PATCH /users/me,
│   │                      POST/DELETE /users/me/avatar, POST /users/me/password, GET /users?q=)
│   ├── teams.py           Справочник команд (GET /teams)
│   ├── admin.py           Администрирование конференций, пользователей, команд, настроек инстанса
│   ├── health.py          GET /api/health
│   ├── metrics.py         GET /metrics (Prometheus)
│   ├── conferences.py     Динамические конференции (create, my, calendar, resolve,
│   │                      join, guest-join, GET/PATCH/DELETE /{id})
│   ├── chat.py            WS-эндпоинт чата (auth по LiveKit-токену, история, broadcast через Redis pub/sub)
│   └── livekit_webhook.py Webhook-приёмник событий LiveKit
├── core/                   Основные модули
│   ├── config.py          Конфиг из .env (Settings)
│   ├── security.py        Hash/verify пароля (argon2), JWT токены
│   ├── db.py              Управление сеансами БД (async)
│   ├── redis.py           Redis клиент
│   ├── rate_limit.py      Rate limiting для публичных endpoint'ов
│   ├── summarization/     Чанкинг транскрипта, LLM-клиент, подсчёт токенов
│   └── plugins/           Контракты Transcriber/Summarizer, factory, реализации
│       ├── transcriber.py     Контракт Transcriber
│       ├── summarizer.py      Контракт Summarizer
│       ├── config.py          Pydantic-конфиг плагинов
│       ├── factory.py         Регистрация и создание провайдеров
│       ├── null.py            NullTranscriber, NullSummarizer (no-op)
│       ├── faster_whisper.py  FasterWhisperCPU, FasterWhisperGPU
│       └── qwen_local.py      QwenLocal (map-reduce суммаризация через llama.cpp)
├── models/                SQLAlchemy ORM (14 таблиц, см. docs/db/schema.md)
│   ├── base.py            Base class
│   ├── user.py            User
│   ├── team.py             Team (справочник команд)
│   ├── email_verification.py  EmailVerificationToken
│   ├── conference.py      Conference (номер, slug, владелец, recurrence)
│   ├── invitee.py         ConferenceInvitee (приглашённые: user_id ИЛИ email)
│   ├── guest.py           GuestAccess (display_name, email)
│   ├── session.py         ConferenceSession (один запуск конференции, pipeline_status)
│   ├── participant.py     ConferenceParticipant (user_id ИЛИ guest_id, session_id)
│   ├── audio_track.py     SessionAudioTrack (аудиодорожка участника)
│   ├── phrase.py          Phrase (текстовые сегменты транскрибации, participant_id, session_id)
│   ├── chat.py            ChatMessage (автор: пользователь ИЛИ гость, author_name, session_id)
│   ├── email_delivery.py  EmailDelivery (журнал отправленных писем)
│   ├── instance_setting.py InstanceSetting (key-value настройки инстанса, JSONB)
│   └── webhook_event.py   LivekitWebhookEvent
├── repositories/          Async слой доступа к данным
│   ├── users.py
│   ├── conferences.py
│   ├── chat.py            ChatMessageRepository (последние N сообщений, добавление)
│   └── admin.py
├── services/              Бизнес-логика
│   ├── auth.py                Аутентификация (регистрация, вход)
│   ├── conferences.py         CRUD и валидация конференций, жизненный цикл, участники, .ics-приглашения
│   ├── conference_access.py   Проверка доступа (пароль, статус ended)
│   ├── conference_ids.py      Генерация номера (9 цифр) и slug (base64url)
│   ├── recurrence.py          RecurrenceRule, развёртка occurrences
│   ├── avatars.py             Загрузка, валидация (magic bytes), удаление аватаров
│   ├── profile.py             Обновление профиля (ФИО, команда)
│   ├── invitations_producer.py  Постановка .ics-приглашений в очередь Celery
│   ├── chat.py                 ChatService (auth по LiveKit-токену, history, persist+publish)
│   ├── livekit_tokens.py       Генерация LiveKit JWT-токенов
│   ├── webhook_handlers.py     Обработчики webhook-событий от LiveKit
│   ├── egress.py                Запуск/остановка записи аудио через LiveKit Egress
│   ├── email.py / email_templates.py  Отправка писем (саммари, приглашения)
│   ├── ics.py                  Генерация .ics-приглашений
│   ├── instance_settings.py    Эффективная конфигурация инстанса (уровень AI, чат и т.д.)
│   ├── ai_levels.py / ai_tiers.py  Матрица уровней AI (min/medium/max), детект доступности
│   └── pipeline_producer.py    Постановка задач пайплайна пост-обработки в Celery
├── schemas/               Pydantic-схемы для запросов/ответов
│   ├── auth.py            Auth, профиль пользователя
│   ├── admin.py           Админка (конференции, пользователи, команды, настройки)
│   ├── conferences.py     ConferenceCreateIn/UpdateIn, ConferenceOut, JoinOut, ResolveOut, OccurrenceOut, InviteeIn/Out
│   └── chat.py            ChatAuthIn, ChatMessageIn/Out, ChatHistoryOut, ChatErrorOut
├── alembic/               Миграции БД
│   ├── versions/          9 миграций от initial schema до teams/avatars/settings
│   └── env.py
├── scripts/               Утилиты
│   ├── __init__.py
│   ├── seed.py                    Идемпотентный сид: единственный админ-пользователь
│   └── apply_preset_settings.py   Применить настройки инстанса под пресет install.sh
├── tests/                 Тесты (pytest, см. полный список файлов в каталоге)
│   ├── conftest.py
│   ├── test_health.py
│   ├── test_auth.py / test_rbac.py / test_tokens.py
│   ├── test_conferences_api.py / test_conference_service.py / test_recurrence.py
│   ├── test_chat_ws.py
│   ├── test_admin_api.py / test_admin_teams.py / test_teams_api.py / test_users_api.py
│   ├── test_plugins_factory.py / test_qwen_local.py / test_llm_client.py
│   ├── test_pipeline.py / test_build_phrases.py / test_summarize_task.py / test_notify_task.py
│   └── ...
├── main.py                Точка входа FastAPI приложения
└── README.md               Этот файл
```

## Быстрый старт

### Требования

- Python 3.12+
- `uv`: `brew install uv`
- PostgreSQL 16 + Redis (через docker-compose или локально)

### 1. Установка зависимостей

```bash
cd backend
uv sync
```

### 2. Запуск миграций

```bash
uv run alembic upgrade head
```

Создаёт 14 таблиц и включает расширение PostgreSQL `btree_gist` (установлено, но
на текущей схеме не используется ни одним constraint'ом).

### 3. Загрузка тестовых данных (опционально)

```bash
uv run python -m scripts.seed
```

Идемпотентный сид: создаёт единственного администратора (`SEED_ADMIN_EMAIL` /
`SEED_ADMIN_PASSWORD`), если его ещё нет. Конференции создаются пользователями
динамически, предустановленных данных не требуется.

### 4. Запуск сервера

```bash
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

API доступен по адресу `http://localhost:8000`.

Документация:
- Swagger: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

## Тестирование

```bash
# Запуск всех тестов
uv run pytest -q

# Запуск с покрытием
uv run pytest --cov=. --cov-report=html

# Запуск конкретного теста
uv run pytest tests/test_health.py -v
```

## Качество кода

```bash
# Linting
uv run ruff check .

# Проверка форматирования
uv run ruff format --check .

# Автоматическое форматирование
uv run ruff format .

# Проверка типов
uv run mypy .
```

Все проверки должны пройти перед мёржем.

## Конфигурация

### Переменные окружения (`.env`)

Полный список переменных (БД, Redis, JWT, LiveKit, Coturn, email/SMTP, уровни
AI, обнаруженное железо для install.sh и т.д.) и их назначение — см.
[docs/deploy/env.md](../docs/deploy/env.md). Модель `Settings` в
`core/config.py` — единственный источник дефолтов.

### Конфигурация плагинов (`config/plugins.yaml`)

```yaml
transcriber:
  enabled: true
  provider: "null"
  model: null
  language: ru

summarizer:
  enabled: true
  provider: "null"
  model: null
  chunk_minutes: 20

chat:
  enabled: true
```

Подробнее о плагинах см. [docs/plugins/contracts.md](../docs/plugins/contracts.md).

## База данных

### Схема

**14 ORM моделей:**
- `users` — зарегистрированные пользователи
- `teams` — справочник команд
- `email_verification_tokens` — одноразовые токены верификации email
- `conferences` — постоянные сущности конференций (номер, slug, владелец, recurrence)
- `conference_invitees` — приглашённые на конференцию (пользователь или внешний email)
- `guest_access` — гости, представившиеся при входе (display_name, email)
- `conference_sessions` — один запуск конференции (pipeline_status, summary_data)
- `conference_participants` — отслеживание присутствия в сеансе (user_id ИЛИ guest_id, session_id)
- `session_audio_tracks` — аудиодорожки участников сеанса
- `phrases` — текстовые сегменты транскрибации (participant_id, session_id)
- `chat_messages` — сообщения в сеансе (session_id, автор — пользователь или гость)
- `email_deliveries` — журнал отправленных писем
- `instance_settings` — key-value настройки инстанса (JSONB)
- `livekit_webhook_events` — журнал webhook-событий для идемпотентности

Полную ER-диаграмму и обоснования дизайна см. [docs/db/schema.md](../docs/db/schema.md).

### Миграции

Alembic управляет схемой:

```bash
# Проверить текущую версию
uv run alembic current

# Обновить до последней версии
uv run alembic upgrade head

# Создать миграцию после изменений модели
uv run alembic revision --autogenerate -m "description"
```

**Правило:** Модель + миграция коммитятся вместе; никогда только модель.

### Временные метки

Все `DateTime(timezone=True)` сохраняются как UTC в PostgreSQL. Клиент преобразует в локальный часовой пояс.

## API

Полная спецификация: [docs/api/README.md](../docs/api/README.md).

- `GET /api/health` — проверка здоровья (БД, Redis)
- `GET /metrics` — метрики Prometheus
- `/api/v1/auth/*` — регистрация, подтверждение email, вход, refresh, выход
- `/api/v1/users/*` — профиль, аватар, смена пароля, поиск пользователей
- `/api/v1/teams` — справочник команд
- `/api/v1/conferences/*` — создание, календарь, вход по ссылке/номеру, гостевой вход, изменение/удаление
- `WS /api/v1/conferences/{id}/chat` — текстовый чат в реальном времени
- `/api/v1/admin/*` — администрирование конференций, пользователей, команд, настроек
- `/api/v1/livekit/webhook` — приёмник webhook-событий LiveKit

## Плагины

Контракты плагинов в `backend/core/plugins/`:

**Transcriber:**
```python
class Transcriber(ABC):
    provider: ClassVar[str]
    def transcribe(self, audio_path: str, language: str = "ru") -> list[Segment]: ...
```

**Summarizer:**
```python
class Summarizer(ABC):
    provider: ClassVar[str]
    def summarize(self, transcript: str) -> str: ...
```

**Реализации:**
- `NullTranscriber`, `NullSummarizer` — no-op (`provider: "null"`, дефолт)
- `FasterWhisperCPU`, `FasterWhisperGPU` — [docs/plugins/transcriber.md](../docs/plugins/transcriber.md)
- `QwenLocal` — map-reduce суммаризация через llama.cpp — [docs/plugins/summarizer.md](../docs/plugins/summarizer.md)

**Как добавить новый плагин:**
1. Создайте класс, наследующий Transcriber/Summarizer
2. Декоратор: `@register_transcriber` или `@register_summarizer`
3. Укажите провайдера в `config/plugins.yaml`

Все контракты и фабрика: [docs/plugins/contracts.md](../docs/plugins/contracts.md).

## Celery воркеры

Пост-обработка (транскрибирование, суммаризация, email-уведомления и
приглашения) выполняется в Celery-воркерах. См. [workers/README.md](../workers/README.md).

## Решение проблем

**ImportError:**
```bash
uv sync --all-extras
```

**Ошибка подключения к БД:**
```bash
docker compose -f ../deploy/docker-compose.yml ps
echo $DATABASE_URL
```

**Миграции не выполняются:**
```bash
uv run alembic current
uv run alembic downgrade base
uv run alembic upgrade head
```

**Ошибки типов:**
- Python 3.12+: `python --version`
- Пересборка: `uv sync --refresh`

## Процесс разработки

1. **Ветка:** `git checkout -b feature/my-feature`
2. **Напишите тесты:** `tests/test_*.py`
3. **Реализуйте** в соответствующем модуле
4. **Качество:** `pytest -q && ruff check . && mypy .`
5. **Коммит:** включите резюме тестов

Пример:
```
feat: добавить реестр Transcriber плагинов

- Реализовать декоратор @register_transcriber
- Добавить NullTranscriber no-op реализацию
- Добавить test_plugins_factory.py

Тесты: пройдены
```

## Ссылки

- [Корневой README](../README.md) — обзор проекта
- [Схема БД](../docs/db/schema.md) — ER диаграмма & дизайн
- [Контракты плагинов](../docs/plugins/contracts.md) — гайд расширений плагинов
- [API справка](../docs/api/README.md) — endpoint'ы
- [Архитектура](../docs/architecture/README.md) — дизайн системы
- [Dev Setup](../docs/deploy/dev-setup.md) — локальное окружение