voidea/docs/instructions/04-ai-dev-instruction.md

VoIdeaAI — Инструкция для AI-разработчика (локальная разработка + деплой)

Назначение

Эта инструкция — для AI-агента, который продолжает разработку проекта VoIdeaAI. Работа ведётся локально, деплой — отправкой на сервер.

---

1. Архитектура проекта

voidea/
├── app/                    # Backend (Python FastAPI)
│   ├── api/v1/            # HTTP endpoints
│   ├── agents/            # Системные агенты
│   ├── core/              # Конфиг, БД, security
│   ├── integrations/      # AI, OAuth, Telegram, Calendar
│   ├── models/            # SQLAlchemy модели
│   ├── schemas/           # Pydantic схемы
│   ├── services/          # Бизнес-логика
│   └── tasks/             # Celery задачи
├── webui/                 # Frontend (React + Vite + Tailwind)
├── flutter/               # Mobile app (Flutter, отдельная разработка)
├── deploy/                # Файлы деплоя
│   ├── gitea/             # Docker Compose для Gitea
│   ├── images/            # Docker образы (tar)
│   ├── voideaai.nginx.conf
│   └── voidea-api.service / voidea-worker.service / voidea-beat.service (systemd — legacy)
├── docs/instructions/     # Инструкции для AI
├── Dockerfile             # Multi-stage сборка (frontend + backend)
├── docker-compose.yml     # 4 сервиса: app, worker, db, redis
└── .env.production        # Шаблон .env для сервера

2. Технологический стек

Компонент	Технология
Backend	Python 3.12, FastAPI, SQLAlchemy async
Frontend	React 18, Vite, Tailwind CSS, TypeScript
Mobile	Flutter (на сервер НЕ деплоится)
Database	PostgreSQL 16
Queue	Celery + Redis 7
Auth	JWT (access + refresh)
AI	Yandex GPT, GigaChat (fallback chain)
Server	Ubuntu 24.04, Docker Compose, хост-нетворкинг

3. Локальный запуск для разработки

3.1 Backend

# Виртуальное окружение
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Зависимости
pip install -r requirements.txt

# PostgreSQL (локально или через Docker)
# БД: voidea, user: voidea, pass: voidea_pass, port: 5432

# Миграции
alembic upgrade head

# Запуск
uvicorn app.main:app --reload --port 8020

3.2 Frontend

cd webui
npm ci
npm run dev

3.3 Mobile (Flutter)

cd flutter
flutter pub get
flutter run

4. Процесс деплоя

Важно: на сервере НЕ dev-окружение. Все правки — локально, затем деплой.

Основной сценарий

# 1. Внести изменения локально
# 2. Закоммитить
git add .
git commit -m "feat: описание изменения"

# 3. Запушить в Gitea
git push origin master

# 4. На сервере
ssh angel@81.177.141.34
cd /opt/projects/voidea

# 4a. Получить изменения
git pull

# 4b. Пересобрать и перезапустить
docker compose up -d --build

# 4c. Проверить
curl -s http://localhost:8020/health

Миграции БД

# Накатить
docker compose exec app alembic upgrade head

# Откатить
docker compose exec app alembic downgrade -1

Просмотр логов

docker compose logs --tail=50 app
docker compose logs --tail=50 worker

5. Структура .env на сервере

Файл .env в /opt/projects/voidea/.env. Шаблон — .env.production в корне репозитория.

Важные отличия от .env.example:

• DATABASE_URL использует порт 5444 (а не 5432)
• REDIS_URL использует порт 6380 (а не 6379)
• Порты изменены, чтобы не конфликтовать с проектом aegisone на том же сервере

6. Важные ограничения

Серверные (VPS)

• Bridge-сеть не работает — только network_mode: host
• Docker build всегда с network: host
• Docker Hub может таймаутить на больших образах (>100MB) — используйте docker save/docker load
• Всего 20GB диска, ~13GB свободно. Следите за df -h /

Кодовые

• Не трогать .env на сервере (секреты)
• flutter/ — только локальная разработка, в .dockerignore, на сервер не деплоится
• webui/node_modules/ — в .gitignore, не коммитить
• Миграции БД — через alembic, не вручную

7. Docker-образы

Образы хранятся в deploy/images/ в формате .tar. Список используемых образов:

• postgres:16-alpine — voidea + gitea
• redis:7-alpine — voidea
• gitea/gitea:latest-rootless — Gitea
• Образ самого приложения собирается из Dockerfile

Для обновления образов на сервере:

# Локально: скачать и запаковать
docker pull postgres:16-alpine
docker save postgres:16-alpine -o deploy/images/postgres.tar
scp deploy/images/postgres.tar angel@81.177.141.34:/home/angel/

# На сервере:
docker load -i /home/angel/postgres.tar

8. Полезные команды на сервере

# Статус проектов
docker compose -p voidea ps
docker compose -p gitea ps
docker compose -p nginx-proxy ps

# Логи VoIdea
docker compose -p voidea logs --tail=100 -f app

# Перезапуск конкретного сервиса
docker compose -p voidea restart app

# Полная пересборка
docker compose -p voidea up -d --build

# Очистка кеша Docker
docker builder prune -af
docker system prune -af

# Проверка nginx
docker compose -p nginx-proxy exec nginx nginx -t
docker compose -p nginx-proxy exec nginx nginx -s reload

9. Порты на сервере

Порт	Сервис	Проект
8020	FastAPI	VoIdea
5444	PostgreSQL	VoIdea
6380	Redis	VoIdea
3000	Gitea	Gitea
5433	PostgreSQL	Gitea
80/443	nginx-proxy	Общий
8000	FastAPI	aegisone (чужой)
5432	PostgreSQL	aegisone (чужой)

Не занимать порты, помеченные как чужие.

---

Обновлён: 2026-05-19