841 lines
43 KiB
Markdown
841 lines
43 KiB
Markdown
# 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`
|
||
|
||
**Пример запроса:**
|
||
```python
|
||
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 Распознавание речи
|
||
|
||
**Цепочка приоритетов:**
|
||
1. **Web Speech API** (браузер, `SpeechRecognition`) — основной, бесплатный, работает онлайн
|
||
2. **MediaRecorder → Whisper API** (OpenAI `whisper-1`, `language=ru`) — fallback если Web Speech недоступен
|
||
3. Если ключ 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 }
|
||
```
|
||
|
||
**Пример ответа:**
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
При обработке запроса:
|
||
1. Выборка успешных interaction (rating ≥ 4, confidence ≥ 70) за последние 7 дней
|
||
2. Сравнение через `_text_similarity()` — пересечение множеств слов
|
||
3. Если 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 Схема
|
||
|
||
```sql
|
||
-- 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:**
|
||
1. Дирижёр создаёт сессию «Стартап в экологии»
|
||
2. Маршрутизация → Бизнес-аналитик
|
||
3. Бизнес-аналитик генерирует: ROI, окупаемость, ЦА, конкуренты
|
||
4. Верификация: confidence 92%, verified
|
||
5. Ответ + звёзды рейтинга
|
||
|
||
**UI:**
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ ← Стартап в экологии [85%] │
|
||
│ │
|
||
│ Придумай идею для стартапа... │
|
||
│ ─────────────────────────────────── │
|
||
│ Бизнес-аналитик [92%] │
|
||
│ Идея: переработка пластика... │
|
||
│ ★ ★ ★ ★ ☆ │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### Пример 2: Пользователь уточняет
|
||
|
||
**Запрос:** «А какие юридические риски?»
|
||
|
||
1. Дирижёр определяет: нужен Юрист
|
||
2. Юрист анализирует: 152-ФЗ, ответственность за экологию
|
||
3. Confidence: 73% → warning
|
||
4. Пользователь может уточнить или поставить оценку
|
||
|
||
### Пример 3: Сохранение идеи
|
||
|
||
**Команда:** «Сохрани идею»
|
||
|
||
1. Дирижёр → Хранитель
|
||
2. Хранитель формулирует: название, описание, теги
|
||
3. Идея сохраняется в БД + экспорт на Яндекс.Диск (если OAuth подключён)
|
||
|
||
---
|
||
|
||
## 19. Файловая структура (ключевые файлы)
|
||
|
||
```
|
||
voidea/
|
||
├── app/
|
||
│ ├── api/v1/
|
||
│ │ ├── auth.py — аутентификация + OAuth + password reset
|
||
│ │ ├── voice.py — транскрибация, чат, сессии, рейтинг
|
||
│ │ ├── ideas.py — CRUD идей
|
||
│ │ ├── admin.py — админ-панель
|
||
│ │ └── agents.py — управление агентами
|
||
│ ├── agents/
|
||
│ │ ├── conductor_agent.py — Дирижёр (оркестратор)
|
||
│ │ ├── role_agents.py — 13 ролевых агентов + верификация
|
||
│ │ ├── conductor_storage.py — логирование, рейтинг, похожие кейсы
|
||
│ │ ├── registry.py — 12 dev/ops агентов
|
||
│ │ └── base.py — базовый класс агента
|
||
│ ├── core/
|
||
│ │ ├── config.py — настройки (.env)
|
||
│ │ ├── security.py — JWT, bcrypt, хеши
|
||
│ │ ├── middleware.py — SecurityHeadersMiddleware
|
||
│ │ ├── limiter.py — shared slowapi limiter
|
||
│ │ ├── dependencies.py — get_db, get_current_user
|
||
│ │ └── database.py — async SQLAlchemy engine
|
||
│ ├── models/
|
||
│ │ ├── user.py, idea.py, session.py, conductor.py
|
||
│ │ ├── voice_command.py, agent.py, backlog.py, log.py
|
||
│ ├── services/
|
||
│ │ ├── auth_service.py — логин, регистрация, OAuth, brute force
|
||
│ │ ├── session_service.py — CRUD сессий
|
||
│ │ ├── whisper_service.py — OpenAI Whisper API
|
||
│ │ ├── llm_service.py — единый LLM-клиент
|
||
│ │ ├── email_service.py — SMTP + Jinja2
|
||
│ │ ├── password_reset_service.py — JWT reset token
|
||
│ │ └── crypto_service.py — AES-256 Fernet
|
||
│ └── integrations/oauth/
|
||
│ ├── yandex.py — Яндекс OAuth + Disk (работает)
|
||
│ ├── google.py — Google OAuth + Drive (stub, ждёт OAuth)
|
||
│ └── apple.py — Apple OAuth + iCloud (stub, ждёт OAuth)
|
||
├── webui/
|
||
│ ├── src/
|
||
│ │ ├── components/
|
||
│ │ │ ├── VoiceChat.tsx — чат + сайдбар + text input
|
||
│ │ │ ├── VoiceInput.tsx — микрофон (Speech → Whisper)
|
||
│ │ ├── pages/
|
||
│ │ │ ├── LoginPage.tsx, RegisterPage.tsx
|
||
│ │ │ ├── ForgotPasswordPage.tsx, ResetPasswordPage.tsx
|
||
│ │ │ ├── OAuthCallback.tsx
|
||
│ │ └── hooks/
|
||
│ │ └── useVoiceCommands.ts — голосовые команды
|
||
│ ├── public/
|
||
│ │ ├── favicon.ico / .svg / .png
|
||
│ │ ├── apple-touch-icon.png
|
||
│ │ ├── site.webmanifest
|
||
│ │ └── icons/ (192, 512, android-chrome)
|
||
│ └── index.html
|
||
├── alembic/versions/
|
||
│ └── 001_create_all_tables.py
|
||
├── docs/
|
||
│ ├── full.md ← данный файл (финальная спецификация)
|
||
│ ├── architecture.md — архитектурная документация
|
||
│ └── decision-log.md — лог ключевых решений
|
||
├── .env.example
|
||
└── requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
*VoIdeaAI — идеи рождаются вслух, решения приходят мгновенно!*
|
||
*Документ финальной спецификации. Версия 1.0.0.*
|