Files

T

angel 688d043dad Initial commit: VoIdeaAI - voice-first AI idea assistant

2026-05-13 12:51:42 +03:00

43 KiB

Raw Blame History

VoIdeaAI — Финальная спецификация проекта

Роль: ты — старший архитектор ПО и продуктовый аналитик. Твоя задача — зафиксировать полное описание, промпты, архитектуру и все функциональные связи продукта VoIdeaAI.

Цель: голосовой AI-ассистент для генерации, проработки и сохранения идей с помощью группового ИИ-анализа. Пользователь говорит или печатает — система через оркестратора (Дирижёр) направляет запрос специализированному ролевому агенту, верифицирует ответ и возвращает результат с оценкой уверенности.

1. Общая архитектура

Browser (PWA — React + TypeScript + Tailwind)
  │  Web Speech API (распознавание) / SpeechSynthesis (озвучивание)
  │  HTTPS
  ▼
Nginx (reverse proxy, SSL termination, Let's Encrypt)
  │
  ▼
FastAPI (Python 3.12+, async)
  ├── StaticFiles — /assets, /icons, SPA fallback
  ├── SecurityHeadersMiddleware — CSP, HSTS, X-Frame-Options и др.
  ├── CORSMiddleware — whitelist origins
  ├── Limiter (slowapi) — rate limiting на все endpoints
  │
  ├── API v1 (/api/v1)
  │   ├── /auth     — регистрация, логин, OAuth, сброс пароля
  │   ├── /voice    — транскрибация, чат, сессии, рейтинг
  │   ├── /users    — профиль, настройки
  │   ├── /ideas    — CRUD идей
  │   ├── /agents   — список и управление агентами
  │   ├── /admin    — панель управления
  │   └── /sync     — синхронизация
  │
  ├── ConductorAgent (Дирижёр) — оркестратор, точка входа
  │   ├── → 13 Role Agents (ролевые)
  │   └── Верификация (confidence 0-100%)
  │
  ├── AgentRegistry — 12 Dev/Ops агентов (автоматизация)
  │
  ├── LLM Service — OpenAI-compatible (OpenAI / YandexGPT / GigaChat)
  ├── Whisper Service — транскрибация аудио
  ├── Email Service — SMTP (Jinja2), password reset
  ├── Crypto Service — AES-256 Fernet (PBKDF2 600k итераций)
  │
  └── PostgreSQL — 8 таблиц (asyncpg)

Ключевые принципы:

PostgreSQL только — единый DATABASE_URL, без SQLite
No Docker — systemd + venv напрямую на VPS (Ubuntu)
Single-page app — FastAPI StaticFiles раздаёт фронтенд
Агенты имеют прямой доступ к БД — через переданную async-сессию

2. Технологический стек

Компонент	Технология
Бэкенд	Python 3.12+, FastAPI, Uvicorn
Фронтенд	React 18, TypeScript, Tailwind CSS, Vite
PWA	manifest.json, service worker, иконки всех размеров
База данных	PostgreSQL 15+, asyncpg, SQLAlchemy 2.0 (async), Alembic
Аутентификация	JWT (HS256), bcrypt (passlib), OAuth 2.0
ИИ-модели	OpenAI API (gpt-4o-mini), YandexGPT, GigaChat (fallback chain)
Распознавание речи	Web Speech API (браузер) → Whisper API (OpenAI, fallback)
Синтез речи	SpeechSynthesis API (браузер, русский голос)
Шифрование	AES-256-CBC + HMAC-SHA256 (Fernet), PBKDF2
Rate limiting	slowapi (60/min default, 10/min auth, 3/min forgot-password)
Защита заголовков	CSP, HSTS, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection
Почта	aiosmtplib + Jinja2 (HTML-шаблоны)
Мониторинг	Prometheus + Grafana (VPS)
Развёртывание	systemd + venv, Nginx + certbot (Let's Encrypt)

3. Аутентификация и OAuth

3.1 Email + пароль

Регистрация: POST /api/v1/auth/register — email, пароль (8+ символов), имя
Логин: POST /api/v1/auth/login — email + пароль
JWT access token (60 мин) + refresh token (30 дней) с ротацией
bcrypt для хешей паролей
Brute-force защита: 5 неудачных попыток → блокировка на 15 минут (in-memory, в проде — Redis)
Rate limit: 10/min на login, 5/min на register, 3/min на forgot-password

3.2 Яндекс OAuth

7 scopes: login:email, login:info, login:avatar, cloud_api:disk.write, cloud_api:disk.app_folder, cloud_api:disk.read, cloud_api:disk.info
Папка на Диске: /VoIdeaAI/
Методы: upload_file(), ensure_app_folder(), get_disk_info()
Redirect URI настраивается через OAUTH_YANDEX_REDIRECT_URI

3.3 Google OAuth

Scopes: userinfo.email, userinfo.profile, drive.file
Папка на Диске: /VoIdeaAI/
Активируется когда OAUTH_GOOGLE_ID не пуст
Redirect: http://localhost:8020/auth/google/callback

Пример запроса:

from app.integrations.oauth.google import is_available, get_authorize_url, exchange_code, get_user_info, upload_file

if is_available():
    url = await get_authorize_url()
    token = await exchange_code(code)
    user = await get_user_info(token["access_token"])
    await upload_file(token["access_token"], "idea.txt", content)

3.4 Apple OAuth

Sign in with Apple через appleid.apple.com
Активируется когда OAUTH_APPLE_ID не пуст
Redirect: http://localhost:8020/auth/apple/callback
iCloud Drive через CloudKit API

3.5 Password Reset

JWT reset token с отдельным секретом (JWT_RESET_SECRET_KEY), 1 час
HTML-письмо с кнопкой сброса (Jinja2-шаблон)
Если SMTP не настроен — лог в консоль
Rate limit: 3/min на forgot-password

3.6 2FA (TOTP)

Включается через ENABLE_2FA=true
PyOTP + QR-код для настройки
Подтверждение кода при входе после пароля/OAuth

4. Голосовой ввод / вывод

4.1 Распознавание речи

Цепочка приоритетов:

Web Speech API (браузер, SpeechRecognition) — основной, бесплатный, работает онлайн
MediaRecorder → Whisper API (OpenAI whisper-1, language=ru) — fallback если Web Speech недоступен
Если ключ OpenAI не задан — возвращается ошибка

Компонент VoiceInput (webui/src/components/VoiceInput.tsx):

Кнопка-микрофон с визуальной индикацией записи
onMouseDown/onTouchStart — начало записи
onMouseUp/onTouchEnd — остановка и отправка
Автоматическая остановка через 5 секунд (MediaRecorder)
Подавление шума через confidence ≥ 0.5

4.2 Текстовый ввод

Поле ввода рядом с микрофоном, отправка по Enter
Пользователь может говорить ИЛИ печатать
Чекбокс «Озвучивать ответ» отключает TTS

4.3 Синтез речи (TTS)

SpeechSynthesis API браузера (бесплатно, без серверной нагрузки)
Язык: ru-RU, скорость: 0.9
Автоматическое озвучивание ответов (кроме needs_clarification)
Кнопка «Стоп» для прерывания

4.4 Голосовые команды

Фоновый SpeechRecognition (continuous mode) слушает команды:

Команда	Действие
«Стоп»	Остановить TTS
«Повтори»	Повторить последний ответ
«Уточнить»	Открыть диалог уточнения запроса

Отключается при отсутствии сообщений в чате
Confidence ≥ 0.5 для фильтрации шума

5. Оркестрация: Дирижёр

Файл: app/agents/conductor_agent.py

Дирижёр — единственная точка входа для пользовательских запросов. Полный pipeline:

User Input (текст/голос)
  │
  ▼
┌─ 0. Авто-создание сессии ─────────────────┐
│  Если session_id не передан → создаётся    │
│  новая сессия + LLM генерирует title       │
└────────────────────────────────────────────┘
  │
  ▼
┌─ 1. Сбор контекста ───────────────────────┐
│  • Недавние обсуждения пользователя (5)    │
│  • Похожие успешные кейсы (word overlap)   │
│  • История текущей сессии                  │
└────────────────────────────────────────────┘
  │
  ▼
┌─ 2. Маршрутизация (LLM) ──────────────────┐
│  "Определи лучшего агента для ответа"      │
│  temperature=0.3, max_tokens=64            │
│  Ответ ТОЛЬКО именем агента               │
└────────────────────────────────────────────┘
  │
  ▼
┌─ 3. Генерация ответа ─────────────────────┐
│  Выбранный RoleAgent + system_prompt       │
│  temperature=0.7, max_tokens=1536          │
└────────────────────────────────────────────┘
  │
  ▼
┌─ 4. Верификация ──────────────────────────┐
│  Проверка: галлюцинации, противоречия,     │
│  логические ошибки, пропущенные детали     │
│  temperature=0.2, max_tokens=1024          │
│  Ответ JSON: confidence, issues, corrected │
└────────────────────────────────────────────┘
  │
  ▼
┌─ 5. Confidence scoring ───────────────────┐
│  ≥ 80%  → verified (зелёный)               │
│  50-79% → warning (жёлтый)                 │
│  < 50%  → needs_clarification (красный)    │
│  issues_found → ответ скорректирован       │
└────────────────────────────────────────────┘
  │
  ▼
┌─ 6. Логирование + самообучение ───────────┐
│  ConductorInteraction: input, output,       │
│  confidence, agent, время, session_id      │
└────────────────────────────────────────────┘
  │
  ▼
Response { response, agent_name, confidence,
           verification_status, session_id,
           interaction_id }

Пример ответа:

{
  "response": "Идея стартапа по экологии имеет ROI 150%...",
  "agent_name": "Бизнес-аналитик",
  "agent_description": "Оценивает идею с точки зрения бизнес-показателей",
  "confidence": 85,
  "verification_status": "verified",
  "processing_time_ms": 2340.5,
  "interaction_id": "a1b2c3d4-...",
  "session_id": "e5f6g7h8-..."
}

6. Ролевые агенты (13 шт)

Все агенты описаны в app/agents/role_agents.py. Каждый имеет name, description и system_prompt.

#	Агент	Описание	System prompt
1	Бизнес-аналитик	Оценивает идею: ROI, окупаемость, ЦА, конкуренты	«Ты — Бизнес-аналитик. Дай оценку по критериям: ROI (%), срок окупаемости (месяцы), целевая аудитория (тыс. чел.), конкурентные преимущества...»
2	Организатор задач	Разбивает на шаги, план реализации	«Разбей идею на 5-7 шагов. Для каждого: название, срок, ответственный...»
3	Юрист	Проверяет на законы РФ (152-ФЗ, 44-ФЗ и др.)	«Проанализируй на соответствие законодательству РФ. Правовые риски, способы минимизации...»
4	Финансовый консультант	Бюджет, прогноз доходов, точка безубыточности	«Составь смету: разработка, маркетинг, поддержка. Прогноз дохода за год...»
5	Архитектор решений	2 варианта архитектуры (монолит / микросервисы)	«Предложи 2 варианта. Вариант A — монолит, B — микросервисы. Технологии, сложность...»
6	Тестировщик	Тест-кейсы (позитивные/негативные), инструменты	«5-10 тест-кейсов. Шаги, ожидаемый результат, инструменты автоматизации...»
7	UI-дизайнер	2 варианта дизайна, цвета, шрифты, UX	«2 варианта главного экрана. Цветовая схема, шрифты, расположение элементов...»
8	SMM-специалист	Контент-план на месяц, платформы, хештеги	«Контент-план: платформы (ВК, Telegram), форматы, частота, 3-4 примера постов...»
9	Лайф-коуч	SMART-цели, квартальные этапы, метрики	«Помоги сформулировать цель по SMART. Q1-Q4, 3 метрики прогресса...»
10	Эксперт по доступности	Инклюзивность, WCAG 2.1 (AA)	«Слабовидящие, глухие, моторные нарушения, когнитивные — доработки для WCAG 2.1...»
11	Критик	Конструктивный разбор: подводные камни, улучшения	«Что НЕ учтено? Подводные камни, улучшения. Тон — доброжелательный коллега...»
12	Копирайтер	Продающий текст, сторителлинг	«Упакуй идею в яркий текст: заголовки, метафоры, сторителлинг. Для инвесторов и команды...»
13	Хранитель	Сохраняет идею в БД (название, описание, теги)	«Оформи для сохранения: Название, Описание, Теги. Строгий формат...»

Агенты 11-13 (Критик, Копирайтер, Хранитель) добавлены дополнительно к базовым 10 из оригинальной спецификации.

7. Dev/Ops агенты (12 шт)

Зарегистрированы в app/agents/registry.py. Используются через AgentRegistry.run_agent() для автоматизации разработки и поддержки.

#	Агент	Описание
1	DocAgent	Генерация документации по коду
2	BacklogAgent	Управление бэклогом задач
3	SpecAgent	Написание спецификаций
4	AuditAgent	Аудит кода и безопасности
5	ObserverAgent	Мониторинг и наблюдаемость
6	EvolutionAgent	Предложения по эволюции кода
7	SecurityAgent	Проверки безопасности
8	QATesterAgent	Автоматическое тестирование
9	FixAgent	Исправление типовых ошибок
10	UITestAgent	UI-тестирование
11	RolloutAgent	Развёртывание и релизы
12	ConductorAgent	Дирижёр (в registry для Dev/Ops контекста)

8. Связи агентов

                    ┌──────────────────┐
                    │   Пользователь   │
                    │  (голос / текст) │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │    Дирижёр       │ ←── AgentRegistry
                    │  (Conductor)     │     (Dev/Ops)
                    └────────┬─────────┘
                             │ маршрутизация (LLM)
                             ▼
              ┌──────────────────────────────┐
              │      13 Role Agents          │
              │                              │
              │  Бизнес-аналитик             │
              │  Организатор задач           │
              │  Юрист                       │
              │  Финансовый консультант       │
              │  Архитектор решений          │
              │  Тестировщик                 │
              │  UI-дизайнер                 │
              │  SMM-специалист              │
              │  Лайф-коуч                   │
              │  Эксперт по доступности      │
              │  Критик                      │
              │  Копирайтер                  │
              │  Хранитель                   │
              └──────────────┬───────────────┘
                             │ response
                             ▼
                    ┌──────────────────┐
                    │   Верификация    │
                    │ (внутри Дирижёра)│
                    │ confidence 0-100 │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │    Пользователь  │
                    │   + лог в БД    │
                    └──────────────────┘

Ключевые правила:

Дирижёр — единственная точка входа для пользователя
Верификация выполняется внутри Дирижёра (не отдельный агент) — быстрее, меньше загрузки LLM
Dev/Ops агенты вызываются через /api/v1/agents/ (не через Дирижёр)
26 агентов всего: 1 Дирижёр + 13 ролевых + 12 dev/ops
Все ролевые агенты имеют прямой доступ к БД через переданную db: AsyncSession

9. Самообучение

9.1 Рейтинг (1-5)

После каждого ответа пользователь может поставить оценку:

Звёзды 1-5 в интерфейсе
POST /api/v1/voice/rate — сохраняет user_rating в ConductorInteraction
Используется для фильтрации успешных кейсов

9.2 Похожие кейсы (word overlap)

При обработке запроса:

Выборка успешных interaction (rating ≥ 4, confidence ≥ 70) за последние 7 дней
Сравнение через _text_similarity() — пересечение множеств слов
Если overlap > 30% — кейс подмешивается в контекст LLM

Пример:

Было: "придумай идею для стартапа в экологии"
Ответ: "Идея: переработка пластика..." (rating: 5)

Подмешивается в контекст похожего запроса.

9.3 Динамические команды

Хранятся в таблице voice_commands (привязка к user_id)
Если фраза сработала 3+ раза — система предлагает добавить как команду
Поля: phrase, action, agent_name, count, is_active

9.4 ConductorInteraction (таблица логов)

Поле	Описание
`user_id`	FK → users
`session_id`	FK → sessions
`input_text`	Запрос пользователя
`detected_intent`	Распознанное намерение
`selected_agent`	Какой агент отвечал
`response_text`	Ответ агента
`user_rating`	1-5 (заполняется позже)
`confidence_score`	0-100
`verification_status`	verified / warning / needs_clarification / issues_found
`processing_time_ms`	Время обработки
`context`	JSON с деталями верификации

10. Сессии

Модель: app/models/session.py, таблица sessions

1 сессия = 1 обсуждение идеи
Авто-создание при первом сообщении без session_id
Дирижёр формирует заголовок через LLM (до 7 слов) на основе первого запроса
Статусы: active, archived
Привязка к idea_id (когда идея сохранена)

API:

GET /api/v1/voice/sessions — список сессий пользователя
GET /api/v1/voice/sessions/{id} — детали сессии
GET /api/v1/voice/sessions/{id}/history — история взаимодействий
DELETE /api/v1/voice/sessions/{id} — удалить сессию

UI:

Сайдбар слева со списком сессий
Кнопка «Новый чат» → сброс текущей сессии
Активная сессия подсвечена
Кнопка удаления с confirm-диалогом

11. Интеграции с дисками

Единый интерфейс для облачных хранилищ. Все провайдеры создают папку /VoIdeaAI/ и загружают файлы туда.

11.1 Яндекс.Диск (реализован)

app/integrations/oauth/yandex.py:

get_authorize_url() → URL авторизации
exchange_code(code) → токен
get_user_info(token) → профиль
ensure_app_folder(token) → создаёт /VoIdeaAI/
upload_file(token, local_path, remote_name) → загружает файл
get_disk_info(token) → квота

11.2 Google Drive

app/integrations/oauth/google.py:

Активируется при непустом OAUTH_GOOGLE_ID
is_available() → bool
Те же методы: get_authorize_url, exchange_code, get_user_info, ensure_app_folder, upload_file, get_disk_info
Использует https://www.googleapis.com/drive/v3

11.3 Apple iCloud Drive

app/integrations/oauth/apple.py:

Активируется при непустом OAUTH_APPLE_ID
is_available() → bool
Те же методы (через CloudKit API)
Требует дополнительной настройки entitlements в Apple Developer Console

12. Безопасность

12.1 Криптография

Компонент	Метод
Пароли	bcrypt (passlib, 12 раундов)
JWT Access Token	HS256, 60 мин, отдельный secret
JWT Refresh Token	HS256, 30 дней, ротация при каждом использовании
JWT Reset Token	HS256, 1 час, отдельный secret (`JWT_RESET_SECRET_KEY`)
Шифрование данных	AES-256-CBC + HMAC-SHA256 (Fernet), PBKDF2 600k итераций
Шифруются: идеи, ответы ConductorInteraction, логи

12.2 Rate Limiting

Endpoint	Лимит
`/login`	10/min
`/register`	5/min
`/refresh`	10/min
`/forgot-password`	3/min
`/reset-password`	5/min
`/oauth/*`	10/min
`/health`	30/min
Все остальные	60/min

12.3 Security Headers

Все ответы содержат:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'; script-src 'self'; ...

12.4 Brute Force

5 неудачных попыток логина за 15 минут → временная блокировка email
In-memory (TODO: Redis в production)
Не блокирует другие аккаунты с того же IP

12.5 Дополнительно

CORS whitelist (настраивается)
Токены в localStorage (с предупреждением о XSS)
SQLAlchemy ORM (параметризованные запросы — защита от SQL injection)
Pydantic-валидация всех входящих данных
is_active check на каждом запросе
require_admin dependency для админ-роутов

13. База данных (PostgreSQL)

13.1 Схема

-- 8 таблиц, все с UUID первичными ключами + created_at/updated_at

users
  id              UUID PRIMARY KEY
  email           VARCHAR(255) UNIQUE NOT NULL
  password_hash   VARCHAR(255) NULLABLE
  display_name    VARCHAR(255) NOT NULL
  avatar_url      VARCHAR(512) NULLABLE
  is_active       BOOLEAN DEFAULT true
  is_superuser    BOOLEAN DEFAULT false
  oauth_provider  VARCHAR(50) NULLABLE
  oauth_id        VARCHAR(255) NULLABLE

ideas
  id              UUID PRIMARY KEY
  user_id         UUID FK → users(id) ON DELETE CASCADE
  title           VARCHAR(255) NOT NULL
  description     TEXT
  tags            TEXT
  status          VARCHAR(20) DEFAULT 'draft'

agent_configs
  id              UUID PRIMARY KEY
  agent_name      VARCHAR(100) NOT NULL
  user_id         UUID FK → users(id) ON DELETE CASCADE
  model           VARCHAR(100)
  enabled         BOOLEAN DEFAULT true

backlog_tasks
  id              UUID PRIMARY KEY
  title           VARCHAR(255) NOT NULL
  description     TEXT
  priority        INTEGER DEFAULT 0
  status          VARCHAR(20) DEFAULT 'pending'

log_entries
  id              UUID PRIMARY KEY
  level           VARCHAR(10) NOT NULL
  message         TEXT NOT NULL
  agent           VARCHAR(100)
  user_id         UUID FK → users(id) ON DELETE SET NULL

conductor_interactions
  id              UUID PRIMARY KEY
  user_id         UUID FK → users(id) ON DELETE SET NULL
  session_id      UUID FK → sessions(id) ON DELETE SET NULL
  input_text      TEXT NOT NULL
  detected_intent VARCHAR(100)
  selected_agent  VARCHAR(100)
  response_text   TEXT
  user_rating     INTEGER NULLABLE
  confidence_score INTEGER DEFAULT 80
  verification_status VARCHAR(20) DEFAULT 'verified'
  was_auto_routed BOOLEAN DEFAULT true
  processing_time_ms FLOAT
  context         TEXT (JSON)

sessions
  id              UUID PRIMARY KEY
  user_id         UUID FK → users(id) ON DELETE CASCADE
  title           VARCHAR(255) DEFAULT 'Новое обсуждение'
  status          VARCHAR(20) DEFAULT 'active'
  idea_id         UUID FK → ideas(id) ON DELETE SET NULL

voice_commands
  id              UUID PRIMARY KEY
  user_id         UUID FK → users(id) ON DELETE CASCADE
  phrase          VARCHAR(255) NOT NULL
  action          VARCHAR(50) NOT NULL
  agent_name      VARCHAR(100) NULLABLE
  count           INTEGER DEFAULT 0
  is_active       BOOLEAN DEFAULT true

13.2 Индексы

users.email — UNIQUE
users(oauth_provider, oauth_id) — для OAuth lookup
conductor_interactions(user_id) — история пользователя
conductor_interactions(session_id) — история сессии
sessions(user_id, status) — список сессий
voice_commands(user_id) — команды пользователя

14. Фронтенд (PWA)

14.1 Страницы и маршруты

Маршрут	Страница	Описание
`/`	Главная	SPA entry point
`/login`	LoginPage	Email + Яндекс OAuth + ссылка «Забыли пароль?»
`/register`	RegisterPage	Регистрация email+password
`/forgot-password`	ForgotPasswordPage	Форма ввода email
`/reset-password?token=`	ResetPasswordPage	Новый пароль
`/oauth/callback`	OAuthCallback	Обработка OAuth callback
`/voice`	VoiceChat	Голосовой ассистент с сайдбаром
`/ideas`	IdeaList	Список идей
`/ideas/new`	IdeaCreate	Новая идея
`/ideas/:id`	IdeaEdit	Редактирование идеи

14.2 Ключевые компоненты

VoiceChat — основной интерфейс: сайдбар сессий, список сообщений, confidence badge, звёзды рейтинга, кнопка «Уточнить», голосовые команды
VoiceInput — кнопка микрофона, Web Speech API → Whisper fallback
VoiceCommands — хук useVoiceCommands для фоновых команд «Стоп»/«Повтори»/«Уточнить»
AuthContext — контекст аутентификации: login(), register(), logout(), refreshToken()
Layout — навигация, пункт «Голос»
OAuthCallback — обработка кода авторизации
ForgotPasswordPage / ResetPasswordPage — сброс пароля

14.3 PWA

manifest.json с иконками всех размеров (16, 32, 192, 512, apple-touch-icon)
favicon.ico + SVG fallback
service worker (Vite PWA plugin)
Тёмная тема (Tailwind dark: классы)
Адаптивный дизайн (mobile-first)

15. API Reference

15.1 Auth (`/api/v1/auth`)

Метод	Endpoint	Тело	Ответ
POST	`/register`	`{email, password, display_name}`	`TokenResponse`
POST	`/login`	`{email, password}`	`TokenResponse`
POST	`/refresh`	`{refresh_token}`	`TokenResponse` (ротация)
GET	`/oauth/yandex`	—	`{url, provider}`
POST	`/oauth/yandex/callback`	`{code}`	`TokenResponse`
GET	`/oauth/google`	—	`{url, provider}`
POST	`/oauth/google/callback`	`{code}`	`TokenResponse`
GET	`/oauth/apple`	—	`{url, provider}`
POST	`/oauth/apple/callback`	`{code}`	`TokenResponse`
POST	`/forgot-password`	`{email}`	`{message}`
POST	`/reset-password`	`{token, new_password}`	`{message}`

15.2 Voice (`/api/v1/voice`)

Метод	Endpoint	Тело / Параметры	Ответ
POST	`/transcribe`	`file: UploadFile` (audio)	`{text}`
POST	`/chat`	`{text, session_id?}`	`ChatResponse`
POST	`/rate`	`{interaction_id, rating}`	`{status}`
GET	`/agents`	—	`[{name, description}]`
GET	`/sessions`	`?status=`	`[SessionResponse]`
GET	`/sessions/{id}`	—	`SessionResponse`
GET	`/sessions/{id}/history`	—	`[{interactions}]`
DELETE	`/sessions/{id}`	—	`{status}`

15.3 Ideas (`/api/v1/ideas`)

Метод	Endpoint	Описание
GET	`/`	Список идей
POST	`/`	Создать идею
GET	`/{id}`	Детали идеи
PUT	`/{id}`	Обновить идею
DELETE	`/{id}`	Удалить идею

15.4 Admin (`/api/v1/admin`)

Под защитой require_admin:

GET /users — список пользователей
GET /logs — просмотр логов
GET /agents — статус агентов

16. Фазы реализации

Фаза 0: База данных — Модели (8 таблиц), миграция Alembic, SQLAlchemy async, UUID primary keys
Фаза 1: Сессии — Авто-создание сессии, авто-title (LLM), сайдбар, история, удаление
Фаза 2: Сохранение идей — Хранитель (Keeper Agent), кнопка «Сохранить», экспорт на Яндекс.Диск / Google Drive / iCloud
Фаза 3: Команды + самообучение — Встроенные и динамические голосовые команды, VoiceHelpPage, docs/voice-commands.md
Фаза 4: UI/анимация — Dark-стили VoiceChat, анимированная волна микрофона, микро-анимации переходов
Фаза 5: Multi-сессия — BroadcastChannel API, параллельные обсуждения, переключение между сессиями без потери контекста
Фаза 6: Rate limit — Применение slowapi ко всем auth endpoints, настройка лимитов
Фаза 7: Security hardening — Security headers middleware, brute force (5 попыток), refresh token rotation, отдельный reset secret
Фаза 8: 2FA (TOTP) — PyOTP + QR-код, подтверждение кода при входе, настройка через профиль
Фаза 9: VPS deploy — Nginx + certbot (Let's Encrypt) + systemd + Alembic upgrade + production .env + мониторинг
Фаза 10: Google/Apple OAuth — Активация роутов авторизации, Drive клиенты, полная интеграция с дисками

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

Решение	Обоснование
PostgreSQL-only	Единый `DATABASE_URL`. Никакого SQLite. Дев и прод на одном PostgreSQL
systemd (no Docker)	Прямое управление процессом, простота деплоя на Ubuntu VPS
FastAPI StaticFiles	Фронтенд раздаётся бэкендом — не нужен отдельный сервер для SPA
Дирижёр = единственная точка входа	Верификация внутри Дирижёра (не отдельный агент) — быстрее, меньше загрузки LLM
Confidence scoring	≥80% OK, 50-79% warning, <50% уточнение. Прозрачность для пользователя
Web Speech → Whisper	Бесплатный браузерный API как primary, Whisper API как fallback
SpeechSynthesis (TTS)	Браузерный API — бесплатно, без серверной нагрузки
Пустой OAuth ID = флаг	`bool(oauth_google_id)` — естественный gate, не может быть рассинхрона
Отдельный JWT reset secret	Reset token не может быть использован как access/refresh и наоборот
Refresh token rotation	Каждый refresh выдаёт новую пару — старый токен становится недействительным
Brute force in-memory	Достаточно для MVP. В проде — Redis с TTL
Агенты имеют прямой доступ к БД	Все внутренние агенты работают через переданную async-сессию

18. Примеры использования

Пример 1: Пользователь придумывает стартап

Запрос: «Придумай идею для стартапа в сфере экологии»

Pipeline:

Дирижёр создаёт сессию «Стартап в экологии»
Маршрутизация → Бизнес-аналитик
Бизнес-аналитик генерирует: ROI, окупаемость, ЦА, конкуренты
Верификация: confidence 92%, verified
Ответ + звёзды рейтинга