voidea/docs/runbook/01-quick-start.md

Quick Start - VoIdea

Дата: 2026-05-10 Обновлено: автоматически DocAgent

---

Prerequisites

Перед началом убедитесь, что установлено:

Компонент	Версия	Ссылка
Python	3.12+	python.org
PostgreSQL	14+	postgresql.org
Git	2.0+	git-scm.com

---

1. Клонирование проекта

git clone <repository_url>
cd voidea

---

2. Настройка виртуального окружения

Windows

python -m venv venv
.\venv\Scripts\activate

Linux/macOS

python -m venv venv
source venv/bin/activate

---

3. Установка зависимостей

pip install -r requirements.txt

---

4. Настройка PostgreSQL

Windows

1. Скачайте и установите PostgreSQL с postgresql.org
2. Запустите pgAdmin или psql

Создание базы данных

-- Подключитесь к 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. Настройка переменных окружения

cp .env.example .env

Откройте .env и заполните:

# Обязательно заполнить
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

python -c "import secrets; print(secrets.token_hex(32))"

---

6. Миграции базы данных

# Создание миграций (если ещё нет)
alembic revision --autogenerate -m "Initial migration"

# Применение миграций
alembic upgrade head

---

7. Запуск приложения

Локальный режим (разработка)

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. Тесты

# Все тесты
pytest

# С покрытием
pytest --cov=app --cov-report=html

# Конкретный файл
pytest tests/unit/test_core.py -v

---

9. Code Quality

# Линтинг
ruff check .

# Форматирование
ruff format .

# Типизация
mypy app

---

10. Генерация Design Tokens (опционально)

# После изменений в 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         # Зависимости

---

Обновление проекта

# Переключиться на новую версию
git checkout develop
git pull origin develop

# Применить миграции
alembic upgrade head

# Обновить зависимости
pip install -r requirements.txt

---

Решение проблем

"Module not found"

pip install -r requirements.txt

"Database connection refused"

1. Проверьте PostgreSQL запущен
2. Проверьте DB_HOST, DB_PORT в .env
3. Проверьте credentials

"Port already in use"

# Найти процесс на порту 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 автоматически