# 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 автоматически*