Initial commit: VoIdeaAI - voice-first AI idea assistant

docs/runbook/01-quick-start.md

@@ -0,0 +1,247 @@
+# Quick Start - VoIdea
+
+**Дата:** 2026-05-10
+**Обновлено:** автоматически DocAgent
+
+---
+
+## Prerequisites
+
+Перед началом убедитесь, что установлено:
+
+| Компонент | Версия | Ссылка |
+|-----------|--------|--------|
+| Python | 3.12+ | [python.org](https://www.python.org/downloads/) |
+| PostgreSQL | 14+ | [postgresql.org](https://www.postgresql.org/download/) |
+| Git | 2.0+ | [git-scm.com](https://git-scm.com/) |
+
+---
+
+## 1. Клонирование проекта
+
+```bash
+git clone <repository_url>
+cd voidea
+```
+
+---
+
+## 2. Настройка виртуального окружения
+
+### Windows
+
+```bash
+python -m venv venv
+.\venv\Scripts\activate
+```
+
+### Linux/macOS
+
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+
+---
+
+## 3. Установка зависимостей
+
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## 4. Настройка PostgreSQL
+
+### Windows
+
+1. Скачайте и установите PostgreSQL с [postgresql.org](https://www.postgresql.org/download/windows/)
+2. Запустите pgAdmin или psql
+
+### Создание базы данных
+
+```sql
+-- Подключитесь к PostgreSQL (psql или pgAdmin)
+CREATE USER voidea WITH PASSWORD 'your_secure_password';
+CREATE DATABASE voidea OWNER voidea;
+GRANT ALL PRIVILEGES ON DATABASE voidea TO voidea;
+```
+
+---
+
+## 5. Настройка переменных окружения
+
+```bash
+cp .env.example .env
+```
+
+Откройте `.env` и заполните:
+
+```bash
+# Обязательно заполнить
+DB_PASS=your_secure_password
+JWT_SECRET_KEY=generate_with_python_c_secret
+PROJECT_OWNER=Your Name
+
+# Опционально (для полного функционала)
+AI_YANDEX_KEY=your_yandex_gpt_key
+AI_GIGACHAT_KEY=your_gigachat_key
+OAUTH_YANDEX_ID=your_yandex_client_id
+OAUTH_GOOGLE_ID=your_google_client_id
+```
+
+### Генерация JWT_SECRET_KEY
+
+```bash
+python -c "import secrets; print(secrets.token_hex(32))"
+```
+
+---
+
+## 6. Миграции базы данных
+
+```bash
+# Создание миграций (если ещё нет)
+alembic revision --autogenerate -m "Initial migration"
+
+# Применение миграций
+alembic upgrade head
+```
+
+---
+
+## 7. Запуск приложения
+
+### Локальный режим (разработка)
+
+```bash
+uvicorn app.main:app --reload --port 8020 --host 0.0.0.0
+```
+
+### Проверка работы
+
+Откройте в браузере:
+- API: http://localhost:8020
+- Docs: http://localhost:8020/docs
+- Health: http://localhost:8020/health
+
+---
+
+## 8. Тесты
+
+```bash
+# Все тесты
+pytest
+
+# С покрытием
+pytest --cov=app --cov-report=html
+
+# Конкретный файл
+pytest tests/unit/test_core.py -v
+```
+
+---
+
+## 9. Code Quality
+
+```bash
+# Линтинг
+ruff check .
+
+# Форматирование
+ruff format .
+
+# Типизация
+mypy app
+```
+
+---
+
+## 10. Генерация Design Tokens (опционально)
+
+```bash
+# После изменений в tokens.json
+python -m generators css
+python -m generators swift
+python -m generators kotlin
+```
+
+---
+
+## Структура проекта
+
+```
+voidea/
+├── app/                    # Код приложения
+│   ├── agents/             # 11 системных агентов
+│   ├── core/               # Конфигурация, базовые классы
+│   ├── models/              # Модели данных
+│   ├── api/                # API endpoints
+│   ├── services/           # Бизнес-логика
+│   └── integrations/       # Внешние сервисы
+├── docs/                   # Документация
+│   ├── blocks/             # Блоки проекта
+│   ├── design-system/      # Дизайн-система
+│   ├── instructions/        # Инструкции
+│   └── specs/              # Спецификации
+├── tests/                  # Тесты
+├── CHANGELOG/              # История версий
+├── .env.example            # Пример переменных
+└── requirements.txt         # Зависимости
+```
+
+---
+
+## Обновление проекта
+
+```bash
+# Переключиться на новую версию
+git checkout develop
+git pull origin develop
+
+# Применить миграции
+alembic upgrade head
+
+# Обновить зависимости
+pip install -r requirements.txt
+```
+
+---
+
+## Решение проблем
+
+### "Module not found"
+
+```bash
+pip install -r requirements.txt
+```
+
+### "Database connection refused"
+
+1. Проверьте PostgreSQL запущен
+2. Проверьте `DB_HOST`, `DB_PORT` в `.env`
+3. Проверьте credentials
+
+### "Port already in use"
+
+```bash
+# Найти процесс на порту 8020
+netstat -ano | findstr :8020
+
+# Завершить процесс
+taskkill /PID <pid> /F
+```
+
+---
+
+## Следующие шаги
+
+1. Прочитайте `PROJECT_GUIDE.md` — обзор проекта
+2. Изучите `docs/blocks/00-rules.md` — правила проекта
+3. Следуйте плану в `docs/blocks/PLAN.md` — этапы разработки
+
+---
+
+*Обновлено: 2026-05-10*
+*Этот файл поддерживается DocAgent автоматически*

docs/runbook/02-backup.md

@@ -0,0 +1,25 @@
+# Runbook: Резервное копирование
+
+## PostgreSQL
+
+```bash
+# Ручной бэкап
+pg_dump -U voidea -d voidea > /backups/voidea.$(date +%Y%m%d).sql
+
+# Восстановление
+psql -U voidea -d voidea < /backups/voidea.20260511.sql
+
+# Автоматический (cron: ежедневно в 3:00)
+0 3 * * * pg_dump -U voidea -d voidea | gzip > /backups/voidea.$(date +\%Y\%m\%d).sql.gz && find /backups -name 'voidea.*.sql.gz' -mtime +30 -delete
+```
+
+## Что бэкапить
+
+- Базу данных — ежедневно
+- `.env` — отдельно, в GitHub Secrets / 1Password
+
+## Хранение
+
+- Последние 7 дней: локально
+- Последние 30 дней: S3 / облако
+- Старше 30 дней: удалять

docs/runbook/03-incident.md

@@ -0,0 +1,59 @@
+# Runbook: Инциденты
+
+## Сервис недоступен
+
+```bash
+# 1. Проверить что процесс жив
+systemctl status voidea
+
+# 2. Проверить логи
+journalctl -u voidea -n 50 --no-pager
+
+# 3. Перезапустить
+systemctl restart voidea
+
+# 4. Проверить health
+curl http://localhost:8020/health
+
+# 5. Если не помогло — rollback
+cd /opt/voidea
+git checkout <previous-stable-tag>
+systemctl restart voidea
+```
+
+## База данных недоступна
+
+```bash
+# 1. Проверить PostgreSQL
+systemctl status postgresql
+
+# 2. Проверить логи
+journalctl -u postgresql -n 50
+
+# 3. Перезапустить
+systemctl restart postgresql
+
+# 4. Если повреждена — восстановить из backup
+psql -U voidea -d voidea < /backups/voidea.20260511.sql
+```
+
+## AI провайдер недоступен
+
+- FallbackChain автоматически пробует YandexGPT → GigaChat
+- Если оба недоступны — возвращается AgentResult(success=False)
+- Пользователь получает уведомление, анализ не блокируется
+
+## Высокая загрузка CPU
+
+```bash
+# 1. Найти процесс
+top -o %CPU
+
+# 2. Проверить какие endpoint'ы нагружают
+tail -n 100 /var/log/voidea/access.log
+
+# 3. Временно ограничить: увеличить число воркеров или перезапустить
+systemctl restart voidea
+
+# 4. Разбираться после восстановления
+```

docs/runbook/04-scale.md

@@ -0,0 +1,41 @@
+# Runbook: Масштабирование
+
+## Когда масштабироваться
+
+| Метрика | Действие |
+|---------|----------|
+| CPU > 80% постоянно | Увеличить VPS (больше ядер) |
+| RAM > 80% | Увеличить VPS (больше RAM) |
+| DB > 10M записей | Индексы → шардинг |
+| Response time p95 > 1s | Кэширование (Redis) → реплики БД |
+
+## Vertical scaling (проще)
+
+```bash
+# 1. Остановить сервис
+systemctl stop voidea
+
+# 2. Увеличить ресурсы VPS (через панель управления)
+
+# 3. Запустить
+systemctl start voidea
+```
+
+## Horizontal scaling (сложнее)
+
+```bash
+# 1. Поставить Nginx как load balancer
+# 2. Запустить несколько инстансов uvicorn на разных портах
+# 3. Настроить shared Redis кэш
+# 4. Настроить репликацию PostgreSQL
+```
+
+## Celery worker
+
+```bash
+# Запустить с большим числом воркеров
+celery -A app.tasks worker --concurrency=4 -l info
+
+# Для длительных задач — отдельная очередь
+celery -A app.tasks worker -Q analysis -c 2 -l info
+```

docs/runbook/05-update.md

@@ -0,0 +1,64 @@
+# Runbook: Обновление
+
+## Стандартное обновление
+
+```bash
+# 1. Забрать новую версию
+cd /opt/voidea
+git pull origin main
+
+# 2. Активировать виртуальное окружение
+source venv/bin/activate
+
+# 3. Обновить зависимости
+pip install -r requirements.txt
+
+# 4. Применить миграции БД
+alembic upgrade head
+
+# 5. Перезапустить сервис
+systemctl restart voidea
+
+# 6. Проверить health
+curl http://localhost:8020/api/v1/health
+```
+
+## Обновление с минимальным даунтаймом
+
+```bash
+# 1. Запустить второй инстанс на другом порту
+DATABASE_URL=... uvicorn app.main:app --port 8021 &
+
+# 2. Проверить его health
+curl http://localhost:8021/health
+
+# 3. Переключить systemd или Nginx на новый порт
+# 4. Остановить старый
+```
+
+## Откат
+
+```bash
+# 1. Откатить код
+cd /opt/voidea
+git revert HEAD
+
+# 2. Откатить БД (если была миграция)
+alembic downgrade -1
+
+# 3. Перезапустить
+systemctl restart voidea
+```
+
+## Миграция БД
+
+```bash
+# Сгенерировать новую миграцию
+alembic revision --autogenerate -m "description"
+
+# Применить
+alembic upgrade head
+
+# Откатить
+alembic downgrade -1
+```

docs/runbook/README.md

@@ -0,0 +1,25 @@
+# Runbook - VoIdea
+
+**Purpose:** Operations guide for project owner
+
+---
+
+## Table of Contents
+
+1. [Quick Start](01-quick-start.md)
+2. [Deployment](02-deployment.md)
+3. [Backup & Restore](03-backup-restore.md)
+4. [Troubleshooting](04-troubleshooting.md)
+5. [Monitoring](05-monitoring.md)
+6. [Security](06-security.md)
+
+---
+
+## Overview
+
+This runbook contains operational procedures for VoIdea project.
+All procedures are maintained by system agents (DocAgent, BacklogAgent).
+
+---
+
+*Updated: 2026-05-10*