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
```bash
# Виртуальное окружение
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
```bash
cd webui
npm ci
npm run dev
```

### 3.3 Mobile (Flutter)
```bash
cd flutter
flutter pub get
flutter run
```

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

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

### Основной сценарий
```bash
# 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
```

### Миграции БД
```bash
# Накатить
docker compose exec app alembic upgrade head

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

### Просмотр логов
```bash
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`

Для обновления образов на сервере:
```bash
# Локально: скачать и запаковать
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. Полезные команды на сервере

```bash
# Статус проектов
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*