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