Add deployment documentation and enhance project setup scripts
- Introduced `DEPLOYMENT.md` for comprehensive deployment instructions. - Added `start.bat` and `start.sh` scripts for unified project startup on Windows and Linux/Mac. - Updated `.gitignore` to exclude additional files and directories. - Enhanced `main.py` to serve static frontend files and handle SPA routing. - Configured Vite to output the frontend build to the backend public directory. - Minor adjustments in `ReviewDetail.tsx` for improved data handling.
This commit is contained in:
Primakov Alexandr Alexandrovich
@@ -1,299 +1,330 @@
|
||||
# AI Code Review Agent 🤖
|
||||
# 🤖 AI Code Review Platform
|
||||
|
||||
AI агент для автоматического ревью Pull Request с поддержкой **Gitea**, **GitHub** и **Bitbucket**.
|
||||
|
||||
Работает на **LangChain/LangGraph** с локальной LLM через **Ollama**.
|
||||
|
||||
## 🌟 Особенности
|
||||
|
||||
- ✅ **Поддержка множества Git платформ**: Gitea (приоритет), GitHub, Bitbucket
|
||||
- 🤖 **AI-анализ кода**: использует Ollama с моделью codellama
|
||||
- 🔄 **Real-time обновления**: WebSocket для отслеживания прогресса
|
||||
- 🎯 **Умный анализ**: находит баги, проблемы безопасности, нарушения best practices
|
||||
- 🌐 **Современный UI**: React + TypeScript + Tailwind CSS
|
||||
- 📊 **Дашборд**: статистика и мониторинг ревью
|
||||
- 🪝 **Webhook интеграция**: автоматический запуск при создании/обновлении PR
|
||||
|
||||
## 🏗️ Архитектура
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||||
│ Git Platform│─────▶│ Backend │─────▶│ Ollama │
|
||||
│ (Webhook) │ │ FastAPI + │ │ (codellama)│
|
||||
└─────────────┘ │ LangGraph │ └─────────────┘
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Frontend │
|
||||
│ React + WS │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
## 📋 Требования
|
||||
|
||||
- **Python 3.11+**
|
||||
- **Node.js 18+**
|
||||
- **Ollama** (установлен и запущен)
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### 1. Установка Ollama и модели
|
||||
|
||||
```bash
|
||||
# Установите Ollama с https://ollama.ai/
|
||||
|
||||
# Загрузите модель codellama
|
||||
ollama pull codellama
|
||||
|
||||
# Запустите Ollama
|
||||
ollama serve
|
||||
```
|
||||
|
||||
### 2. Backend (FastAPI)
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Создайте виртуальное окружение
|
||||
python -m venv venv
|
||||
source venv/bin/activate # На Windows: venv\Scripts\activate
|
||||
|
||||
# Установите зависимости
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Создайте .env файл
|
||||
cp .env.example .env
|
||||
|
||||
# Отредактируйте .env и установите:
|
||||
# - SECRET_KEY (генерируйте случайную строку)
|
||||
# - ENCRYPTION_KEY (генерируйте случайную строку)
|
||||
|
||||
# Запустите сервер
|
||||
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
Backend будет доступен на `http://localhost:8000`
|
||||
|
||||
Swagger документация: `http://localhost:8000/docs`
|
||||
|
||||
### 3. Frontend (React)
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Установите зависимости
|
||||
npm install
|
||||
|
||||
# Запустите dev сервер
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Frontend будет доступен на `http://localhost:5173`
|
||||
|
||||
## 🔧 Настройка
|
||||
|
||||
### Backend (.env)
|
||||
|
||||
```env
|
||||
# Ollama
|
||||
OLLAMA_BASE_URL=http://localhost:11434
|
||||
OLLAMA_MODEL=codellama
|
||||
|
||||
# Database
|
||||
DATABASE_URL=sqlite+aiosqlite:///./review.db
|
||||
|
||||
# Security
|
||||
SECRET_KEY=your-secret-key-here
|
||||
ENCRYPTION_KEY=your-encryption-key-here
|
||||
|
||||
# Server
|
||||
HOST=0.0.0.0
|
||||
PORT=8000
|
||||
DEBUG=True
|
||||
|
||||
# CORS
|
||||
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
|
||||
```
|
||||
|
||||
### Frontend (.env)
|
||||
|
||||
```env
|
||||
VITE_API_URL=http://localhost:8000
|
||||
VITE_WS_URL=ws://localhost:8000
|
||||
```
|
||||
|
||||
## 📖 Использование
|
||||
|
||||
### 1. Добавление репозитория
|
||||
|
||||
1. Откройте UI: `http://localhost:5173`
|
||||
2. Перейдите на страницу **Репозитории**
|
||||
3. Нажмите **+ Добавить репозиторий**
|
||||
4. Заполните форму:
|
||||
- **Название**: имя вашего проекта
|
||||
- **Платформа**: Gitea / GitHub / Bitbucket
|
||||
- **URL**: полный URL репозитория
|
||||
- **API токен**: токен доступа к Git платформе
|
||||
|
||||
### 2. Настройка webhook в Gitea
|
||||
|
||||
1. Скопируйте **Webhook URL** из карточки репозитория
|
||||
2. В Gitea: Settings → Webhooks → Add Webhook
|
||||
3. Вставьте URL
|
||||
4. Выберите события: **Pull Request**
|
||||
5. Сохраните
|
||||
|
||||
### 3. Создание Pull Request
|
||||
|
||||
1. Создайте PR в вашем репозитории
|
||||
2. Webhook автоматически запустит ревью
|
||||
3. Следите за прогрессом в UI (страница **Ревью**)
|
||||
4. Комментарии появятся в PR автоматически
|
||||
|
||||
## 🎯 Что анализирует AI
|
||||
|
||||
- 🐛 **Потенциальные баги**: логические ошибки, null/undefined
|
||||
- 🔒 **Безопасность**: SQL injection, XSS, утечки данных
|
||||
- 📝 **Best practices**: SOLID, чистый код, паттерны
|
||||
- ⚡ **Производительность**: неэффективные алгоритмы, утечки памяти
|
||||
- 📖 **Читаемость**: понятность кода, комментарии
|
||||
|
||||
## 📊 API Endpoints
|
||||
|
||||
### Repositories
|
||||
|
||||
- `GET /api/repositories` - список репозиториев
|
||||
- `POST /api/repositories` - добавить репозиторий
|
||||
- `PUT /api/repositories/{id}` - обновить
|
||||
- `DELETE /api/repositories/{id}` - удалить
|
||||
|
||||
### Reviews
|
||||
|
||||
- `GET /api/reviews` - список ревью
|
||||
- `GET /api/reviews/{id}` - детали ревью
|
||||
- `POST /api/reviews/{id}/retry` - повторить ревью
|
||||
- `GET /api/reviews/stats/dashboard` - статистика
|
||||
|
||||
### Webhooks
|
||||
|
||||
- `POST /api/webhooks/gitea/{repository_id}` - Gitea webhook
|
||||
- `POST /api/webhooks/github/{repository_id}` - GitHub webhook
|
||||
- `POST /api/webhooks/bitbucket/{repository_id}` - Bitbucket webhook
|
||||
|
||||
### WebSocket
|
||||
|
||||
- `ws://localhost:8000/ws/reviews` - real-time обновления
|
||||
|
||||
## 🛠️ Разработка
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Запуск с hot reload
|
||||
uvicorn app.main:app --reload
|
||||
|
||||
# Миграции (если используется Alembic)
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Dev сервер
|
||||
npm run dev
|
||||
|
||||
# Сборка
|
||||
npm run build
|
||||
|
||||
# Предпросмотр сборки
|
||||
npm run preview
|
||||
|
||||
# Линтинг
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## 🗂️ Структура проекта
|
||||
|
||||
```
|
||||
platform/review/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── agents/ # LangGraph агенты
|
||||
│ │ ├── api/ # API endpoints
|
||||
│ │ ├── models/ # Database модели
|
||||
│ │ ├── schemas/ # Pydantic схемы
|
||||
│ │ ├── services/ # Git платформы
|
||||
│ │ ├── webhooks/ # Webhook обработчики
|
||||
│ │ ├── config.py
|
||||
│ │ ├── database.py
|
||||
│ │ └── main.py
|
||||
│ └── requirements.txt
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # API клиент
|
||||
│ │ ├── components/ # React компоненты
|
||||
│ │ ├── pages/ # Страницы
|
||||
│ │ ├── types/ # TypeScript типы
|
||||
│ │ └── App.tsx
|
||||
│ └── package.json
|
||||
├── cloud.md # План проекта
|
||||
└── README.md # Этот файл
|
||||
```
|
||||
|
||||
## 🔐 Безопасность
|
||||
|
||||
- API токены шифруются перед сохранением (Fernet)
|
||||
- Webhook signature validation
|
||||
- CORS настроен для конкретных доменов
|
||||
- Rate limiting (рекомендуется для production)
|
||||
|
||||
## 🚀 Production развертывание
|
||||
|
||||
### Docker (рекомендуется)
|
||||
|
||||
```bash
|
||||
# TODO: Добавить Dockerfile и docker-compose.yml
|
||||
```
|
||||
|
||||
### Manual
|
||||
|
||||
1. Используйте PostgreSQL вместо SQLite
|
||||
2. Настройте reverse proxy (nginx)
|
||||
3. Используйте HTTPS
|
||||
4. Настройте environment variables
|
||||
5. Используйте process manager (systemd/supervisor)
|
||||
|
||||
## 🤝 Вклад в разработку
|
||||
|
||||
Contributions welcome!
|
||||
|
||||
1. Fork проект
|
||||
2. Создайте feature branch
|
||||
3. Commit изменения
|
||||
4. Push в branch
|
||||
5. Создайте Pull Request
|
||||
|
||||
## 📝 Лицензия
|
||||
|
||||
MIT License
|
||||
|
||||
## 🙏 Благодарности
|
||||
|
||||
- [LangChain](https://github.com/langchain-ai/langchain) - фреймворк для LLM
|
||||
- [Ollama](https://ollama.ai/) - локальный запуск LLM
|
||||
- [FastAPI](https://fastapi.tiangolo.com/) - веб-фреймворк
|
||||
- [React](https://react.dev/) - UI библиотека
|
||||
|
||||
## 📞 Поддержка
|
||||
|
||||
Возникли проблемы? Создайте Issue в репозитории.
|
||||
Автоматический ревьювер кода на базе AI для Gitea, GitHub и Bitbucket.
|
||||
|
||||
---
|
||||
|
||||
Made with ❤️ and 🤖 AI
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### Запуск одной командой:
|
||||
|
||||
**Windows:**
|
||||
```bash
|
||||
start.bat
|
||||
```
|
||||
|
||||
**Linux/Mac:**
|
||||
```bash
|
||||
chmod +x start.sh
|
||||
./start.sh
|
||||
```
|
||||
|
||||
Это автоматически:
|
||||
- ✅ Проверит зависимости
|
||||
- ✅ Установит пакеты
|
||||
- ✅ Соберет frontend
|
||||
- ✅ Запустит сервер
|
||||
|
||||
**Готово!** Откройте http://localhost:8000
|
||||
|
||||
---
|
||||
|
||||
## 📋 Что делает платформа
|
||||
|
||||
1. **Получает Pull Request** через webhook
|
||||
2. **Анализирует код** с помощью AI (Ollama)
|
||||
3. **Находит проблемы:**
|
||||
- ❌ Критичные ошибки (синтаксис, логика)
|
||||
- ⚠️ Важные замечания (code smell, антипаттерны)
|
||||
- ℹ️ Рекомендации (стиль, best practices)
|
||||
4. **Публикует комментарии** в PR
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Особенности
|
||||
|
||||
- ✅ **3 платформы:** Gitea, GitHub, Bitbucket
|
||||
- ✅ **Webhooks:** Автоматический ревью при создании PR
|
||||
- ✅ **Ручной запуск:** Кнопка "Проверить сейчас"
|
||||
- ✅ **WebSocket:** Обновления в реальном времени
|
||||
- ✅ **Детальные комментарии:** Отдельный комментарий на каждую проблему
|
||||
- ✅ **Мастер токены:** Один токен для всех репозиториев
|
||||
- ✅ **Единый порт:** Frontend и Backend на 8000
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Требования
|
||||
|
||||
- **Python:** 3.10+
|
||||
- **Node.js:** 18+
|
||||
- **Ollama:** Для запуска AI моделей
|
||||
|
||||
### Установка Ollama:
|
||||
|
||||
**Linux:**
|
||||
```bash
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
```
|
||||
|
||||
**Windows/Mac:**
|
||||
Скачайте с https://ollama.com/download
|
||||
|
||||
### Скачайте модель:
|
||||
|
||||
```bash
|
||||
ollama pull mistral:7b
|
||||
# или
|
||||
ollama pull llama3:8b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Настройка
|
||||
|
||||
### 1. Клонируйте репозиторий
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd platform/review
|
||||
```
|
||||
|
||||
### 2. Настройте `.env`
|
||||
|
||||
Файл `backend/.env` будет создан автоматически из `.env.example`.
|
||||
|
||||
**Обязательно настройте:**
|
||||
|
||||
```bash
|
||||
# Ollama
|
||||
OLLAMA_BASE_URL=http://localhost:11434
|
||||
OLLAMA_MODEL=mistral:7b
|
||||
|
||||
# Мастер токены (опционально)
|
||||
MASTER_GITEA_TOKEN=your_token_here
|
||||
|
||||
# Ключ шифрования (обязательно!)
|
||||
ENCRYPTION_KEY=your-32-char-key-here
|
||||
```
|
||||
|
||||
**Генерация ключа:**
|
||||
```python
|
||||
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
```
|
||||
|
||||
### 3. Запустите
|
||||
|
||||
```bash
|
||||
./start.sh # Linux/Mac
|
||||
start.bat # Windows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Использование
|
||||
|
||||
### 1. Добавьте репозиторий
|
||||
|
||||
http://localhost:8000 → **"Добавить репозиторий"**
|
||||
|
||||
- **Платформа:** Gitea/GitHub/Bitbucket
|
||||
- **URL:** https://git.example.com/owner/repo
|
||||
- **API Token:** (или оставьте пустым для мастер токена)
|
||||
|
||||
### 2. Настройте webhook
|
||||
|
||||
Скопируйте webhook URL из списка репозиториев.
|
||||
|
||||
**В Gitea:**
|
||||
Settings → Webhooks → Add Webhook → Gitea
|
||||
- Payload URL: `http://your-server:8000/api/webhooks/gitea/1`
|
||||
- Content Type: `application/json`
|
||||
- Secret: (из списка репозиториев)
|
||||
- Trigger: Pull Request
|
||||
|
||||
### 3. Готово!
|
||||
|
||||
Создайте PR и агент автоматически проведет ревью! 🎉
|
||||
|
||||
Или нажмите **"🔍 Проверить сейчас"** для ручного запуска.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Что вы увидите
|
||||
|
||||
### В интерфейсе:
|
||||
|
||||
```
|
||||
📊 Репозитории: 5
|
||||
🔍 Ревью: 23
|
||||
✅ Успешных: 20
|
||||
❌ Ошибок: 3
|
||||
```
|
||||
|
||||
### В Gitea/GitHub:
|
||||
|
||||
**Общий комментарий:**
|
||||
```
|
||||
🤖 AI Code Review
|
||||
|
||||
📊 Статистика
|
||||
- Всего проблем: 4
|
||||
- ❌ Критичных: 4
|
||||
|
||||
💡 Рекомендации
|
||||
⚠️ Найдены критичные проблемы!
|
||||
Пожалуйста, исправьте их перед мержем.
|
||||
|
||||
📝 Детальные комментарии для каждой
|
||||
проблемы опубликованы ниже.
|
||||
```
|
||||
|
||||
**Отдельные комментарии:**
|
||||
```
|
||||
❌ src/pages/search-character.tsx:58
|
||||
|
||||
ERROR: Опечатка в строке:
|
||||
'shmapplication/json' должно быть
|
||||
'application/json'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Разработка
|
||||
|
||||
### Backend:
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
### Frontend:
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
В режиме разработки:
|
||||
- Frontend: http://localhost:5173
|
||||
- Backend: http://localhost:8000
|
||||
|
||||
---
|
||||
|
||||
## 📁 Структура
|
||||
|
||||
```
|
||||
platform/review/
|
||||
├── backend/ # FastAPI + LangGraph
|
||||
│ ├── app/
|
||||
│ │ ├── agents/ # AI агент
|
||||
│ │ ├── api/ # REST endpoints
|
||||
│ │ ├── models/ # SQLAlchemy models
|
||||
│ │ ├── services/ # Git API clients
|
||||
│ │ └── main.py # Entry point
|
||||
│ ├── public/ # Frontend build (auto-generated)
|
||||
│ └── requirements.txt
|
||||
├── frontend/ # React + Vite
|
||||
│ ├── src/
|
||||
│ └── package.json
|
||||
├── start.sh # Единый запуск (Linux/Mac)
|
||||
├── start.bat # Единый запуск (Windows)
|
||||
└── DEPLOYMENT.md # Подробная документация
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Возможности
|
||||
|
||||
### ✅ Реализовано:
|
||||
|
||||
- [x] Поддержка Gitea, GitHub, Bitbucket
|
||||
- [x] Webhooks для автоматического ревью
|
||||
- [x] Ручной запуск ревью
|
||||
- [x] Детальные комментарии с ссылками на строки
|
||||
- [x] WebSocket для real-time обновлений
|
||||
- [x] Мастер токены для упрощения настройки
|
||||
- [x] Единый запуск (frontend + backend)
|
||||
- [x] Экранирование HTML тегов в комментариях
|
||||
- [x] Контекст PR (title + description) в промпте
|
||||
- [x] Retry механизм для failed ревью
|
||||
- [x] Модальные окна вместо alert/confirm
|
||||
|
||||
### 🚧 Планируется:
|
||||
|
||||
- [ ] Docker контейнер
|
||||
- [ ] Статусы PR (Approve/Request Changes)
|
||||
- [ ] Настраиваемые правила ревью
|
||||
- [ ] Кастомные промпты
|
||||
- [ ] Множественные AI модели
|
||||
- [ ] Метрики и аналитика
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Вклад
|
||||
|
||||
Pull requests приветствуются!
|
||||
|
||||
Для больших изменений сначала откройте issue для обсуждения.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Лицензия
|
||||
|
||||
MIT
|
||||
|
||||
---
|
||||
|
||||
## 📚 Документация
|
||||
|
||||
- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Полное руководство по развертыванию
|
||||
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Архитектура проекта
|
||||
- **[DEBUG_GUIDE.md](DEBUG_GUIDE.md)** - Отладка AI агента
|
||||
- **[MODEL_RECOMMENDATION.md](MODEL_RECOMMENDATION.md)** - Рекомендации по моделям
|
||||
- **[MASTER_TOKEN_FEATURE.md](MASTER_TOKEN_FEATURE.md)** - Мастер токены
|
||||
- **[HTML_ESCAPE_FIX.md](HTML_ESCAPE_FIX.md)** - Экранирование HTML
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Помощь
|
||||
|
||||
### Проблемы с Ollama?
|
||||
|
||||
```bash
|
||||
# Проверьте что Ollama запущен
|
||||
curl http://localhost:11434/api/version
|
||||
|
||||
# Скачайте модель
|
||||
ollama pull mistral:7b
|
||||
```
|
||||
|
||||
### Frontend не отображается?
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Backend не запускается?
|
||||
|
||||
Проверьте `.env` файл и установите `ENCRYPTION_KEY`.
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Начните использовать!
|
||||
|
||||
```bash
|
||||
# 1. Клонируйте
|
||||
git clone <url>
|
||||
cd platform/review
|
||||
|
||||
# 2. Настройте .env
|
||||
nano backend/.env
|
||||
|
||||
# 3. Запустите
|
||||
./start.sh # или start.bat
|
||||
|
||||
# 4. Откройте
|
||||
http://localhost:8000
|
||||
```
|
||||
|
||||
**Готово!** 🚀
|
||||
|
||||
Reference in New Issue
Block a user