# Схема БД

## ER-диаграмма

```mermaid
erDiagram
    USERS ||--o{ CONFERENCES : owns
    USERS ||--o{ CONFERENCE_PARTICIPANTS : joins
    USERS ||--o{ CONFERENCE_INVITEES : invites
    USERS ||--o{ PHRASES : speaks
    USERS ||--o{ CHAT_MESSAGES : "sends (author)"
    USERS ||--o{ EMAIL_VERIFICATION_TOKENS : receives
    CONFERENCES ||--o{ CONFERENCE_INVITEES : "has invitees"
    CONFERENCES ||--o{ CONFERENCE_SESSIONS : "has sessions"
    CONFERENCES ||--o{ GUEST_ACCESS : "may allow"
    CONFERENCES ||--o{ EMAIL_DELIVERIES : "invitations"
    CONFERENCE_SESSIONS ||--o{ CONFERENCE_PARTICIPANTS : tracks
    CONFERENCE_SESSIONS ||--o{ PHRASES : contains
    CONFERENCE_SESSIONS ||--o{ CHAT_MESSAGES : contains
    CONFERENCE_SESSIONS ||--o{ EMAIL_DELIVERIES : "summaries"
    GUEST_ACCESS ||--o{ CONFERENCE_PARTICIPANTS : "may join"
    GUEST_ACCESS ||--o{ CHAT_MESSAGES : "sends (author)"
    LIVEKIT_WEBHOOK_EVENTS ||--o{ CONFERENCE_SESSIONS : "triggers"
    INSTANCE_SETTINGS ||--|| CONFERENCES : "configure"
    TEAMS ||--o{ USERS : "groups"

    USERS {
        uuid id PK
        string email UK
        string name_user
        text password_hash
        string role "admin|user"
        boolean email_verified
        boolean is_blocked
        uuid team_id FK "nullable"
        string avatar_path "nullable"
        datetime created_at
    }

    EMAIL_VERIFICATION_TOKENS {
        uuid id PK
        uuid user_id FK
        string token_hash UK
        datetime expires_at
        datetime used_at "nullable"
        datetime created_at
    }

    CONFERENCES {
        uuid id PK
        string number UK "9 digits"
        string slug UK "base64url"
        string title "nullable"
        uuid owner_id FK "nullable"
        string status "enum: scheduled|active|ended"
        boolean is_pinned
        boolean is_closed
        text password_hash "nullable"
        datetime scheduled_at "nullable"
        integer duration_minutes "nullable"
        jsonb recurrence "nullable"
        datetime ended_at "nullable"
        datetime created_at
    }

    CONFERENCE_INVITEES {
        uuid id PK
        uuid conference_id FK
        uuid user_id FK "nullable, для зарег. пользователей"
        string email "nullable, для внешних"
        datetime created_at
        "CHECK: ровно один из user_id/email"
        "UNIQUE: (conference_id, user_id)"
        "UNIQUE: (conference_id, lower(email))"
    }

    CONFERENCE_SESSIONS {
        uuid id PK
        uuid conference_id FK
        string title "nullable"
        datetime t_start
        datetime t_end "nullable"
        text summary_data "nullable"
        string pipeline_status "enum"
        datetime created_at
    }

    GUEST_ACCESS {
        uuid id PK
        uuid conference_id FK
        string display_name
        string email "nullable"
        datetime created_at
    }

    CONFERENCE_PARTICIPANTS {
        uuid id PK
        uuid session_id FK
        uuid user_id FK "nullable"
        uuid guest_id FK "nullable"
        datetime joined_at
        datetime left_at "nullable"
    }

    SESSION_AUDIO_TRACKS {
        uuid id PK
        uuid session_id FK
        uuid participant_id FK
        string track_sid
        string egress_id "nullable"
        text file_path "nullable"
        string status "enum"
        datetime started_at
        datetime ended_at "nullable"
        jsonb segments "nullable"
    }

    PHRASES {
        bigint id PK "Identity"
        uuid participant_id FK
        uuid session_id FK
        text data
        datetime t_start
        datetime t_end
    }

    CHAT_MESSAGES {
        bigint id PK "Identity"
        uuid session_id FK
        uuid user_id FK "nullable"
        uuid guest_access_id FK "nullable"
        string author_name "255 chars"
        text text
        datetime created_at
    }

    LIVEKIT_WEBHOOK_EVENTS {
        string event_id PK
        string event_type
        datetime received_at
    }

    INSTANCE_SETTINGS {
        string key PK
        jsonb value
        datetime updated_at
    }

    EMAIL_DELIVERIES {
        uuid id PK
        uuid session_id FK "nullable"
        uuid conference_id FK "nullable"
        string recipient_email
        string kind "summary|invitation"
        datetime sent_at
    }
```

## Таблицы

### users
Зарегистрированные пользователи приложения.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `email` | VARCHAR(255) | Уникальный адрес электронной почты |
| `name_user` | VARCHAR(255) | Имя пользователя |
| `password_hash` | TEXT | Argon2-хэш пароля |
| `role` | VARCHAR(16) | 'admin' или 'user'; проверка CHECK |
| `email_verified` | BOOLEAN | Флаг подтверждения почты |
| `is_blocked` | BOOLEAN | Флаг блокировки администратором; заблокированный пользователь получает 401 немедленно, без ожидания истечения access-токена |
| `team_id` | UUID | FK → teams, nullable; `ON DELETE SET NULL` — удаление команды не удаляет пользователей |
| `avatar_path` | VARCHAR(512) | Путь к загруженному аватару (относительно `MEDIA_ROOT`); `NULL` — заглушка с инициалами на фронте; пример: `avatars/550e8400-e29b-41d4-a716-446655440000.jpg` |
| `created_at` | TIMESTAMPTZ | UTC-время создания |

### teams
Справочник команд для группировки пользователей.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `name` | VARCHAR(255) | Название команды; уникально |
| `created_at` | TIMESTAMPTZ | UTC-время создания |

**Логика:** удаление команды не каскадирует на пользователей — `users.team_id` просто обнуляется (`ON DELETE SET NULL`); привязка необязательна.

### email_verification_tokens
Одноразовые токены подтверждения email при регистрации.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `user_id` | UUID | FK → users; CASCADE удаление |
| `token_hash` | TEXT | SHA256-хэш одноразового токена (hex); уникален |
| `expires_at` | TIMESTAMPTZ | Срок действия (UTC); по умолчанию 24 часа от создания |
| `used_at` | TIMESTAMPTZ | Время использования; NULL если не подтверждён |
| `created_at` | TIMESTAMPTZ | UTC-время создания |

**Ограничения:**
- `UNIQUE(token_hash)` — уникальный индекс на хэш токена
- `INDEX(user_id)` — для быстрого поиска токенов пользователя

**Логика:**
- При регистрации создаётся новый токен; клиент получает открытый токен в письме
- Сервер хранит только SHA256-хэш (токен не может быть восстановлен из БД)
- Первое использование (POST /verify-email) заполняет `used_at`, устанавливает `user.email_verified=true`
- Повторное использование того же токена → 400 (used_at IS NOT NULL)

### conferences
Конференция — постоянная сущность с номером и постоянной ссылкой (slug). Может быть мгновенной или плановой с повторением (ADR-001).

**Миграция:** Таблица `conferences` переименована в `conference_sessions` (см. ниже); новая таблица `conferences` создана миграцией `f418dd65e7b1`.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `number` | VARCHAR(9) | 9 десятичных цифр, первая 1..9, уникален; генерируется с retry при коллизии |
| `slug` | VARCHAR(22) | `secrets.token_urlsafe(8)` — 11 base64url-символов; используется как имя комнаты в LiveKit и часть URL `/j/{slug}` |
| `title` | VARCHAR(255) | Опциональное название конференции |
| `owner_id` | UUID | FK → users; SET NULL при удалении пользователя; может быть NULL для исторических данных |
| `status` | ENUM | `scheduled` (плановая, время ещё не наступило), `active` (идёт сейчас), `ended` (завершена; история остаётся) |
| `is_pinned` | BOOLEAN | Закреплена ли (видна в «Моих конференциях», может повторяться) |
| `is_closed` | BOOLEAN | Требуется ли пароль для входа |
| `password_hash` | TEXT | Argon2-хэш пароля (только если is_closed=true); CHECK: `is_closed=false OR password_hash IS NOT NULL` |
| `scheduled_at` | TIMESTAMPTZ | Время запуска (UTC); NULL для мгновенных |
| `duration_minutes` | INT | Ожидаемая длительность в минутах; опционально, для информации |
| `recurrence` | JSONB | RecurrenceRule (JSON с type/weekdays/day_of_month/interval_days/anchor_date/time_local/timezone/duration_minutes); только если is_pinned=true; CHECK: `recurrence IS NULL OR is_pinned = true` |
| `ended_at` | TIMESTAMPTZ | Время завершения (UTC); заполняется при статусе → ended |
| `summary_recipients` | VARCHAR(16) | Переопределение рассылки саммари для конференции: `'all'` (всем участникам и гостям с email), `'owner'` (только организатору), NULL (используется дефолт инстанса) |
| `ics_sequence` | INT | Счётчик изменений расписания: растёт при правке `scheduled_at`, `duration_minutes`, `recurrence`, `title`; пишется в VEVENT SEQUENCE для обновления приглашений календарными клиентами |
| `created_at` | TIMESTAMPTZ | UTC-время создания |

**Ограничения:**
- `UNIQUE(number)` — уникальность номера
- `UNIQUE(slug)` — уникальность постоянной ссылки
- CHECK: `is_closed = false OR password_hash IS NOT NULL`
- CHECK: `recurrence IS NULL OR is_pinned = true`

### conference_sessions
Один запуск конференции, единица AI-пайплайна пост-обработки.

**Миграция:** До миграции `f418dd65e7b1` это была таблица `conferences`; переименована в `conference_sessions`, связь `conference_id` добавлена.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key |
| `conference_id` | UUID | FK → conferences; CASCADE удаление |
| `title` | VARCHAR(255) | Снапшот названия конференции на момент запуска (опционально) |
| `t_start` | TIMESTAMPTZ | Время начала сеанса (UTC) |
| `t_end` | TIMESTAMPTZ | Время окончания сеанса (UTC); опционально, заполняется при завершении |
| `summary_data` | TEXT | JSON со сводкой (заполняется после summarize-шага); опционально |
| `pipeline_status` | ENUM | Статус пайплайна: `recording` → `transcribing` → `summarizing` → `notified` / `failed` |
| `created_at` | TIMESTAMPTZ | UTC-время создания |

**Индексы:**
- `(conference_id, t_start)` для поиска сеансов конференции
- `(pipeline_status)` для поиска активных обработок

Статус-машина пост-обработки живёт в этой таблице (см. ADR-001).

### guest_access
Гость, представившийся при входе в конференцию без аутентификации (ADR-001, п.6).

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key |
| `conference_id` | UUID | FK → conferences; CASCADE удаление |
| `display_name` | VARCHAR(255) | Отображаемое имя гостя (обязательно) |
| `email` | VARCHAR(320) | Адрес электронной почты (опционально; для рассылки саммари) |
| `created_at` | TIMESTAMPTZ | UTC-время создания записи (при первом входе гостем) |

**Назначение:**
- Гость входит в конференцию без аккаунта (публичный эндпоинт `/guest-join`)
- LiveKit identity: `guest:{guest_access.id}`
- Email не передаётся в LiveKit (PII — только в БД)

### conference_participants
Отслеживает присутствие участника (пользователя ИЛИ гостя) в сеансе конференции (ADR-001, п.6).

**Миграция:** Колонка `conference_id` переименована в `session_id` (`f418dd65e7b1`); `user_id` стал nullable; добавлены `guest_id` и CHECK для ровно одного identity.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key |
| `session_id` | UUID | FK → conference_sessions; CASCADE удаление |
| `user_id` | UUID | FK → users; NULL для гостей; nullable |
| `guest_id` | UUID | FK → guest_access; NULL для зарегистрированных; nullable |
| `joined_at` | TIMESTAMPTZ | Время входа (UTC) |
| `left_at` | TIMESTAMPTZ | Время выхода (UTC); опционально |

**Ограничения:**
- CHECK: `(user_id IS NOT NULL)::int + (guest_id IS NOT NULL)::int = 1` — ровно одно из user_id/guest_id заполнено

**Индексы:**
- `(session_id)` для поиска участников сеанса

### conference_invitees

Приглашённые на конференцию участники (зарегистрированные пользователи или внешние email'ы) — ADR-003.

**Миграция:** `d87681e12784`

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `conference_id` | UUID | FK → conferences; CASCADE удаление |
| `user_id` | UUID | FK → users; nullable; CASCADE удаление; заполнено для зарегистрированных пользователей |
| `email` | VARCHAR(255) | Email для внешних приглашённых; nullable; нормализуется в lower-case |
| `created_at` | TIMESTAMPTZ | UTC-время создания приглашения |

**Ограничения:**
- CHECK: `(user_id IS NOT NULL)::int + (email IS NOT NULL)::int = 1` — ровно один из user_id/email должен быть заполнен (единственная identity приглашённого)
- **UNIQUE INDEX `uq_conference_invitees_user`** на `(conference_id, user_id)` WHERE `user_id IS NOT NULL` — один приглашённый пользователь на конференцию
- **UNIQUE INDEX `uq_conference_invitees_email`** на `(conference_id, lower(email))` WHERE `email IS NOT NULL` — один внешний email на конференцию (регистронезависимо)

**Назначение:**
- Хранение состава приглашённых участников, заданного организатором при создании/редактировании конференции
- **Организатор НЕ хранится в этой таблице** — он выводится из `conferences.owner_id` и всегда в составе (инвариант обеспечен конструктивно, без триггеров)
- **Не путать с `conference_participants`** — та таблица фиксирует ФАКТИЧЕСКОЕ присутствие в сеансе; эта — планируемый состав

**Семантика:**
- Дедупликация при POST/PATCH конференции: если организатор передан в массиве participants, он автоматически вычищается (не хранится дважды)
- Внешние приглашённые (email) при входе по ссылке создают запись в `guest_access`, которая затем связывается с `conference_participants` сеанса

### session_audio_tracks

Аудиодорожка сеанса, записанная LiveKit Track Egress. Каждая строка соответствует одному аудиотреку (микрофону) одного участника.

**Таблица используется для:**
- Маппинга файлов записи к участникам сеанса (включая гостей без user_id)
- Отслеживания статуса транскрибации каждого трека (recording → recorded → transcribed / failed)
- Хранения сегментов Whisper в JSONB (`segments`) как промежуточного артефакта пайплайна

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `session_id` | UUID | FK → conference_sessions; CASCADE удаление |
| `participant_id` | UUID | FK → conference_participants; CASCADE удаление; NOT NULL (атрибуция к участнику сеанса, см. ADR-002) |
| `track_sid` | VARCHAR(64) | ID трека в LiveKit (уникален в пределах сеанса с session_id) |
| `egress_id` | VARCHAR(64) | ID egress-задачи в LiveKit; заполняется при старте egress; может быть NULL |
| `file_path` | TEXT | Абсолютный путь к файлу на диске (например, `/recordings/{session_id}/{participant_id}_{track_sid}.ogg`); заполняется при завершении egress |
| `status` | ENUM | Статус трека: `recording` (egress активен) → `recorded` (файл готов) → `transcribed` (Whisper завершил) / `failed` (ошибка на любом шаге) |
| `started_at` | TIMESTAMPTZ | UTC-время старта egress (из EgressInfo) |
| `ended_at` | TIMESTAMPTZ | UTC-время завершения egress; NULL пока трек в статусе `recording` |
| `segments` | JSONB | Список объектов `{start: float, end: float, text: string}` — результат faster-whisper для этого трека; NULL пока не транскрибирован |

**Ограничения:**
- `UNIQUE(session_id, track_sid)` — один трек на сеанс; дедупликация при повторных `track_published`
- Индексы: `(session_id)`, `(session_id, status)` для поиска активных и готовых треков

**Инвариант:**
- Независимый статус трека (отдельно от `conference_sessions.pipeline_status`)
- Тайминги сегментов в `segments` — относительно начала файла (не UTC); абсолютный расчёт: `session.t_start + timedelta(seconds=segment.start)`

### phrases

Восстановленные транскрипт-фразы (результат faster-whisper + реконструкция по алгоритму ТЗ §1.3).

**Изменение:** Колонка `user_id` заменена на `participant_id` (FK → conference_participants), чтобы атрибутировать фразы гостям без user_id (ADR-002).

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | BIGINT | Primary key, Identity(always=True) |
| `participant_id` | UUID | FK → conference_participants; CASCADE удаление; NOT NULL; атрибуция к участнику сеанса |
| `session_id` | UUID | FK → conference_sessions; CASCADE удаление |
| `data` | TEXT | Текст фразы (результат `build_phrases()` — может быть несколько сегментов Whisper одного спикера подряд) |
| `t_start` | TIMESTAMPTZ | Начало фразы (UTC); рассчитывается как `session.t_start + (segment.start + track_offset)` |
| `t_end` | TIMESTAMPTZ | Конец фразы (UTC) |

**Индексы:**
- `(session_id, t_start)` для хронологического поиска фраз в сеансе

**Как получить пользователя/гостя фразы:**
```sql
SELECT p.data, u.name_user, g.display_name
FROM phrases p
JOIN conference_participants cp ON p.participant_id = cp.id
LEFT JOIN users u ON cp.user_id = u.id
LEFT JOIN guest_access g ON cp.guest_id = g.id
WHERE p.session_id = $1
ORDER BY p.t_start;
```

### chat_messages
Текстовые сообщения, отправленные во время сеанса конференции (WS чат).

**Миграции:** 
- `f418dd65e7b1`: колонка `conference_id` переименована в `session_id`
- `504791847d4f`: добавлены `guest_access_id` и `author_name` для поддержки гостевых авторов

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | BIGINT | Primary key, Identity(always=True), уникален в пределах инстанса |
| `session_id` | UUID | FK → conference_sessions; CASCADE удаление |
| `user_id` | UUID | FK → users; nullable; заполнено для авторов-пользователей |
| `guest_access_id` | UUID | FK → guest_access; nullable; CASCADE удаление; заполнено для авторов-гостей |
| `author_name` | VARCHAR(255) | Снапшот отображаемого имени автора из LiveKit access-токена на момент отправки; NOT NULL (переживает переименование пользователя или удаление гостевой записи) |
| `text` | TEXT | Текст сообщения (1..2000 символов) |
| `created_at` | TIMESTAMPTZ | UTC-время создания |

**Ограничения:**
- CHECK: `user_id IS NOT NULL OR guest_access_id IS NOT NULL` — ровно один из user_id/guest_access_id должен быть заполнен (аналогично `conference_participants`, ADR-001 п.6)

**Индексы:**
- `(session_id, created_at)` для хронологического поиска сообщений в сеансе

**Назначение:** Хранение истории чата конференции для отдачи последних N сообщений при подключении нового клиента; публикация в Redis pub/sub для broadcast остальным клиентам

### instance_settings
Настройки инстанса как key-value хранилище (JSONB). Бутстрап из `config/plugins.yaml` при старте backend'а (однократный, идемпотентный импорт).

| Поле | Тип | Описание |
|------|-----|---------|
| `key` | TEXT | Primary key; имя настройки (`transcriber`, `summarizer`, `chat`, `ai_level`, `summary_recipients`, `display_timezone`, `registration_team_choice`, `registration_email_domain`) |
| `value` | JSONB | Значение настройки (структура зависит от ключа) |
| `updated_at` | TIMESTAMPTZ | UTC-время последнего обновления |

**Назначение:**
- Централизованное хранилище конфигурации инстанса (переносит дефолты из `config/plugins.yaml` в БД)
- Административный интерфейс может менять настройки без рестарта приложения
- Воркеры Celery читают конфигурацию на старте каждой задачи (fallback на YAML при пустой таблице)

**Ключи и типы значений (примеры):**
```json
{
  "transcriber": {"enabled": true, "provider": "faster-whisper-cpu", "language": "ru", ...},
  "summarizer": {"enabled": true, "provider": "qwen-local", "chunk_minutes": 20, ...},
  "chat": {"enabled": false},
  "ai_level": {"level": "min"},
  "summary_recipients": {"mode": "all"},
  "display_timezone": {"tz": "Europe/Moscow"},
  "registration_team_choice": {"enabled": true},
  "registration_email_domain": {"enabled": true, "domain": "example.com"}
}
```

### email_deliveries
Журнал отправленных писем (саммари и приглашения). Идемпотентность рассылки саммари и отслеживание доставки.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | UUID | Primary key, генерируется как `gen_random_uuid()` |
| `session_id` | UUID | FK → conference_sessions; NULL для приглашений; заполняется для саммари |
| `conference_id` | UUID | FK → conferences; NULL для саммари; заполняется для приглашений |
| `recipient_email` | VARCHAR(320) | Email получателя (хранится в `lower()` — нормализованный) |
| `kind` | VARCHAR(16) | Тип письма: `'summary'` (саммари сеанса), `'invitation'` (.ics приглашение) |
| `sent_at` | TIMESTAMPTZ | UTC-время отправки (server_default=now()) |

**Ограничения:**
- CHECK: `kind IN ('summary', 'invitation')`
- CHECK: `(kind = 'summary') = (session_id IS NOT NULL)` — саммари обязана иметь session_id
- CHECK: `(kind = 'invitation') = (conference_id IS NOT NULL)` — приглашение обязано иметь conference_id
- **UNIQUE INDEX `uq_email_deliveries_summary`** на `(session_id, recipient_email)` WHERE `kind = 'summary'` — гарантирует, что один адресат получит саммри сеанса один раз (идемпотентность повторной отправки)
- INDEX `ix_email_deliveries_conference` на `conference_id` для быстрого поиска истории приглашений

**Назначение:**
- **Для саммари:** гарантирует идемпотентность — повторный запуск `notify_session` отправляет письмо только тем адресатам, которые ещё не в таблице
- **Для приглашений:** журнал, без unique (изменение расписания конференции переслёт приглашение, допуская дублирование в истории)

### livekit_webhook_events
Журнал идемпотентной доставки webhook-событий от LiveKit.

| Поле | Тип | Описание |
|------|-----|---------|
| `event_id` | VARCHAR(255) | Primary key (уникальный ID события от LiveKit) |
| `event_type` | VARCHAR(64) | Тип события: `room_started`, `participant_joined`, `participant_left`, `room_finished` и др. |
| `received_at` | TIMESTAMPTZ | UTC-время получения события |

**Назначение:**
- Дедупликация: каждое webhook-событие от LiveKit имеет уникальный `event_id`
- При получении события выполняется `INSERT ... ON CONFLICT DO NOTHING` по primary key `event_id`
- Повторная доставка того же события отклоняется на уровне БД; ответ 200 всё равно отправляется (идемпотентность)

## Ключевые решения архитектуры

### UUID как primary key
Все таблицы, кроме `phrases` и `chat_messages`, используют `UUID` генерируемые функцией `gen_random_uuid()`. Это обеспечивает:
- Глобальную уникальность без синхронизации
- Предсказуемую нагрузку на индексы
- Возможность распределённых вставок

### BIGINT Identity для phrases и chat_messages
Высокочастотные таблицы используют `BIGINT Identity(always=True)` — быстрее и проще для очередей обработки фраз/сообщений.

### Номер и slug конференции (9 цифр + base64url)
- **Номер:** 9 десятичных цифр, первая 1..9 (энтропия ≈2^29.75); генерируется с retry при коллизии; задача перебора при rate limit ≈60+ дней; резолв отвечает единообразным 404 (см. ADR-001, п.4)
- **Slug:** `secrets.token_urlsafe(8)` — 11 base64url-символов (64 бита энтропии); используется как имя комнаты в LiveKit и часть URL `/j/{slug}`

### Расширение btree_gist (не используется)
**Миграция `f418dd65e7b1`:** расширение `btree_gist` больше не используется (EXCLUDE constraint на `room_bookings` снят с удалением таблицы, см. ADR-001). Расширение остаётся установленным в БД (безвредно, миграция обратима).

### Все временные метки в UTC
Все столбцы `DateTime(timezone=True)` хранят время в UTC на сервере. Конвертация в локальное время происходит на клиенте на основе часового пояса браузера. iCalendar-экспорт (`.ics`) включает `VTIMEZONE`.

### Enum pipeline_status

Статус пост-обработки сеанса (единица пайплайна) отслеживает жизненный цикл от записи через транскрибацию и суммаризацию до уведомления или ошибки.

**Состояния машины:**

```
recording → transcribing → summarizing → notified / failed
```

| Статус | Описание | Переход | Ответственный |
|--------|---------|---------|---------------|
| `recording` | Сеанс идёт, LiveKit Egress записывает треки | Автоматический при `t_start` сеанса | Backend (создание сеанса) |
| `transcribing` | Транскрибация в процессе | При `run_pipeline()`, после завершения egress | Воркер `run_pipeline` |
| `summarizing` | Суммаризация в процессе | После успешной транскрибации и реконструкции фраз | Воркер `run_pipeline` |
| `notified` | Уведомление отправлено | После успешной суммаризации и отправки email | Воркер уведомлений |
| `failed` | Ошибка на одном из шагов (пайплайн остановлен) | При сбое воркера или если все треки провалены | Воркер `run_pipeline` |

**Идемпотентность:** каждый шаг пайплайна проверяет текущий `pipeline_status` перед началом и пропускает уже завершённые шаги (guard от повторных запусков).

**Пример восстановления после сбоя:**
- Воркер транскрибации упал посеридине обработки треков
- При повторном запуске `run_pipeline(session_id)` проверяет `pipeline_status` = `transcribing`
- Пропускает уже транскрибированные треки (у которых `segments IS NOT NULL`)
- Завершает оставшиеся треки и переходит в `summarizing`

### Идемпотентность через статусы
Каждый шаг пайплайна (транскрибация, суммаризация, уведомление) должен быть идемпотентным: повторное выполнение не приведёт к дублированию или ошибкам. Это достигается через проверку текущего `pipeline_status` перед началом шага.

---

## Миграции

### Миграция d87681e12784

**Участники конференций и аватары пользователей:**

1. **Новая таблица `conference_invitees`** (ADR-003) — приглашённые участники конференции
   - `id` (UUID PK), `conference_id` (FK), `user_id` (nullable FK), `email` (nullable VARCHAR), `created_at`
   - CHECK: ровно одна identity (`user_id` ИЛИ `email`)
   - Частичные UNIQUE индексы по (conference_id, user_id) и (conference_id, lower(email))
   - Организатор не хранится в таблице (выводится из `conferences.owner_id`)

2. **Колонка в `users`:** `avatar_path` (VARCHAR(512), nullable) — путь к загруженному аватару
   - Пример: `avatars/550e8400-e29b-41d4-a716-446655440000.jpg`
   - NULL → заглушка с инициалами на фронте
   - Удаление аватара вычищает файл с диска и обнуляет поле

**SQL:**
```sql
CREATE TABLE conference_invitees (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conference_id UUID NOT NULL REFERENCES conferences(id) ON DELETE CASCADE,
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    email VARCHAR(255),
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    CHECK ((user_id IS NOT NULL)::int + (email IS NOT NULL)::int = 1)
);
CREATE UNIQUE INDEX uq_conference_invitees_user 
  ON conference_invitees(conference_id, user_id) WHERE user_id IS NOT NULL;
CREATE UNIQUE INDEX uq_conference_invitees_email 
  ON conference_invitees(conference_id, lower(email)) WHERE email IS NOT NULL;

ALTER TABLE users ADD COLUMN avatar_path VARCHAR(512);
```

### Миграция 504791847d4f

**Поддержка гостевых авторов в чате:**

1. **Колонки в `chat_messages`:**
   - `guest_access_id` (UUID, nullable) — FK → `guest_access.id`, `ON DELETE CASCADE`; заполнено для авторов-гостей
   - `author_name` (VARCHAR(255), NOT NULL) — снапшот имени автора из LiveKit access-токена на момент отправки; добавляется nullable, backfill из `users.name_user` для уже существующих строк (все они с `user_id`), затем ужесточается до `NOT NULL`

2. **Изменение `chat_messages.user_id`:**
   - Переходит в nullable (вместо NOT NULL), т.к. автором может быть гость

3. **Check-констрейнт:**
   - `ck_chat_messages_author` — `user_id IS NOT NULL OR guest_access_id IS NOT NULL` (ровно один из двух должен быть заполнен)

**Назначение:** WS-чат поддерживает как пользователей, так и гостей как авторов сообщений, с сохранением снапшота имени (для истории и чата).

### Миграция 9d37822e4513

**Справочник команд:**

1. **Новая таблица `teams`** — `id` (UUID PK), `name` (уникально), `created_at`
2. **Колонка в `users`:** `team_id` (UUID, nullable) — FK → `teams.id`, `ON DELETE SET NULL`

**SQL:**
```sql
CREATE TABLE teams (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
ALTER TABLE users ADD COLUMN team_id UUID;
ALTER TABLE users ADD CONSTRAINT fk_users_team_id_teams
    FOREIGN KEY (team_id) REFERENCES teams(id) ON DELETE SET NULL;
```

### Миграция 5970bf64fc43

**Настройки инстанса и уведомления:**

1. **Новая таблица `instance_settings`** — key-value хранилище настроек (JSONB) с бутстрапом из `config/plugins.yaml`
2. **Новая таблица `email_deliveries`** — идемпотентность саммари (уникальный частичный индекс по `(session_id, recipient_email)`) и журнал приглашений
3. **Колонки в `conferences`:**
   - `summary_recipients` (nullable TEXT, CHECK) — переопределение рассылки ('all', 'owner', или NULL=дефолт)
   - `ics_sequence` (INT, default 0) — счётчик для VEVENT SEQUENCE
4. **Колонка в `users`:**
   - `is_blocked` (BOOLEAN, default false) — блокировка администратором

**SQL:**
```sql
CREATE TABLE instance_settings (key TEXT PRIMARY KEY, value JSONB, updated_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE email_deliveries (...);
ALTER TABLE conferences ADD COLUMN summary_recipients VARCHAR(16) CHECK (...);
ALTER TABLE conferences ADD COLUMN ics_sequence INT DEFAULT 0;
ALTER TABLE users ADD COLUMN is_blocked BOOLEAN DEFAULT false;
```

### Миграция 88aa676ac140

**Таблица `session_audio_tracks` и атрибуция фраз (ADR-002):**

1. **Новая таблица `session_audio_tracks`** — аудиотреки сеанса с независимым статусом и сегментами Whisper
2. **Изменение `phrases`: `user_id` → `participant_id`** — атрибуция к участнику сеанса (FK `conference_participants.id`), чтобы работать с гостями без user_id

**Данные (в продакшене):** сохраняются через данные участников (`conference_participants`) и сеансов.

### Миграция f418dd65e7b1

**Переход на динамические конференции (ADR-001):**

1. **Таблица `conferences` → `conference_sessions`** (переименование + новые колонки)
   - Сохранены все данные
   - Добавлена `conference_id` (FK → новая таблица conferences)
   - `pipeline_status` остаётся (семантика не меняется)

2. **Новая таблица `conferences`**
   - Постоянные сущности (номер, slug, владелец, статус, recurrence)
   - Связь с `conference_sessions` (один ко многим, CASCADE удаление)

3. **Новая таблица `guest_access`**
   - Гости, представившиеся при входе
   - display_name обязателен, email опционален

4. **Колонки фраз и сообщений: `conference_id` → `session_id`**
   - `phrases.conference_id` → `phrases.session_id`
   - `chat_messages.conference_id` → `chat_messages.session_id`
   - `conference_participants.conference_id` → `conference_participants.session_id`

5. **Таблицы удалены**
   - `rooms` (комнаты больше не предустановленные)
   - `room_bookings` (бронирования заменены динамическими конференциями)
   - `booking_participants` (доступ теперь по паролю, не по списку)

6. **CHECK-ограничения в новой таблице conferences**
   - `is_closed = false OR password_hash IS NOT NULL`
   - `recurrence IS NULL OR is_pinned = true`

7. **CHECK-ограничение в conference_participants**
   - `(user_id IS NOT NULL)::int + (guest_id IS NOT NULL)::int = 1` — ровно один из user_id/guest_id

8. **Индексы**
   - `(conference_id, t_start)` на conference_sessions
   - `(pipeline_status)` на conference_sessions
   - `(session_id)` на conference_participants