Initial commit: VoIdeaAI - voice-first AI idea assistant

2026-05-13 12:51:42 +03:00
commit 688d043dad
421 changed files with 47915 additions and 0 deletions
@@ -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 автоматически*