init

2025-10-12 23:15:09 +03:00
commit 09cdd06307
88 changed files with 15007 additions and 0 deletions
@@ -0,0 +1,365 @@
+# План создания AI агента-ревьювера
+
+## Обзор проекта
+
+AI агент-ревьювер для автоматического анализа Pull Request с поддержкой Gitea, GitHub и Bitbucket. Работает на LangChain/LangGraph с Ollama.
+
+## Архитектура
+
+```
+platform/review/
+├── backend/
+│   ├── app/
+│   │   ├── __init__.py
+│   │   ├── main.py              # FastAPI приложение
+│   │   ├── config.py            # Конфигурация
+│   │   ├── database.py          # Database setup
+│   │   ├── models/              # SQLAlchemy модели
+│   │   │   ├── __init__.py
+│   │   │   ├── repository.py
+│   │   │   ├── pull_request.py
+│   │   │   ├── review.py
+│   │   │   └── comment.py
+│   │   ├── schemas/             # Pydantic схемы
+│   │   │   ├── __init__.py
+│   │   │   ├── repository.py
+│   │   │   ├── review.py
+│   │   │   └── webhook.py
+│   │   ├── agents/              # LangGraph агенты
+│   │   │   ├── __init__.py
+│   │   │   ├── reviewer.py      # Основной агент-ревьювер
+│   │   │   ├── tools.py         # Инструменты агента
+│   │   │   └── prompts.py       # Промпты для агента
+│   │   ├── services/            # Сервисы интеграций
+│   │   │   ├── __init__.py
+│   │   │   ├── base.py          # Базовый класс
+│   │   │   ├── gitea.py         # Gitea API
+│   │   │   ├── github.py        # GitHub API
+│   │   │   └── bitbucket.py     # Bitbucket API
+│   │   ├── webhooks/            # Webhook обработчики
+│   │   │   ├── __init__.py
+│   │   │   ├── gitea.py
+│   │   │   ├── github.py
+│   │   │   └── bitbucket.py
+│   │   └── api/                 # API endpoints
+│   │       ├── __init__.py
+│   │       ├── repositories.py
+│   │       ├── reviews.py
+│   │       └── webhooks.py
+│   ├── requirements.txt
+│   └── .env.example
+├── frontend/
+│   ├── src/
+│   │   ├── App.tsx
+│   │   ├── main.tsx
+│   │   ├── api/
+│   │   │   ├── client.ts
+│   │   │   └── websocket.ts
+│   │   ├── components/
+│   │   │   ├── RepositoryForm.tsx
+│   │   │   ├── RepositoryList.tsx
+│   │   │   ├── ReviewProgress.tsx
+│   │   │   ├── ReviewList.tsx
+│   │   │   ├── CommentsList.tsx
+│   │   │   └── WebSocketStatus.tsx
+│   │   ├── pages/
+│   │   │   ├── Dashboard.tsx
+│   │   │   ├── Repositories.tsx
+│   │   │   ├── Reviews.tsx
+│   │   │   └── ReviewDetail.tsx
+│   │   └── types/
+│   │       └── index.ts
+│   ├── package.json
+│   ├── vite.config.ts
+│   ├── tsconfig.json
+│   └── index.html
+├── cloud.md                     # Этот файл
+└── README.md
+```
+
+## Технологический стек
+
+### Backend
+- **FastAPI** - веб-фреймворк
+- **LangChain/LangGraph** - фреймворк для AI агента
+- **Ollama** - локальная LLM (модель codellama)
+- **SQLAlchemy** - ORM
+- **SQLite** - база данных
+- **WebSockets** - real-time обновления
+- **httpx** - HTTP клиент для API запросов
+
+### Frontend
+- **React 18** - UI библиотека
+- **TypeScript** - типизация
+- **Vite** - сборщик
+- **TanStack Query** - управление состоянием сервера
+- **WebSocket API** - real-time обновления
+- **Tailwind CSS** - стилизация
+
+## Детальный план реализации
+
+### 1. Backend: Модели данных (SQLAlchemy)
+
+**Repository**
+```python
+- id: int (PK)
+- name: str
+- platform: enum (gitea, github, bitbucket)
+- url: str
+- api_token: str (encrypted)
+- webhook_secret: str
+- config: JSON (настройки ревью)
+- is_active: bool
+- created_at: datetime
+```
+
+**PullRequest**
+```python
+- id: int (PK)
+- repository_id: int (FK)
+- pr_number: int
+- title: str
+- author: str
+- source_branch: str
+- target_branch: str
+- status: enum (open, reviewing, reviewed, closed)
+- url: str
+- created_at: datetime
+- updated_at: datetime
+```
+
+**Review**
+```python
+- id: int (PK)
+- pull_request_id: int (FK)
+- status: enum (pending, analyzing, commenting, completed, failed)
+- started_at: datetime
+- completed_at: datetime
+- files_analyzed: int
+- comments_generated: int
+- error_message: str (nullable)
+```
+
+**Comment**
+```python
+- id: int (PK)
+- review_id: int (FK)
+- file_path: str
+- line_number: int
+- content: str
+- severity: enum (info, warning, error)
+- posted: bool
+- posted_at: datetime (nullable)
+```
+
+### 2. LangGraph агент-ревьювер
+
+**Граф состояний:**
+```
+START → fetch_pr_info → fetch_changed_files → analyze_files → generate_comments → post_comments → END
+                                                     ↓
+                                              (параллельный анализ файлов)
+```
+
+**Узлы графа:**
+1. **fetch_pr_info** - получение информации о PR
+2. **fetch_changed_files** - получение списка измененных файлов
+3. **analyze_files** - анализ каждого файла через Ollama
+4. **generate_comments** - генерация комментариев
+5. **post_comments** - отправка комментариев в PR
+
+**Промпты для Ollama:**
+```
+Системный промпт: "Ты опытный code reviewer. Анализируй код на:
+- Потенциальные баги
+- Проблемы безопасности
+- Нарушения best practices
+- Проблемы производительности
+- Читаемость кода"
+```
+
+### 3. API интеграции (приоритет - Gitea)
+
+**Gitea API endpoints:**
+- `GET /repos/{owner}/{repo}/pulls/{index}` - информация о PR
+- `GET /repos/{owner}/{repo}/pulls/{index}/files` - измененные файлы
+- `GET /repos/{owner}/{repo}/pulls/{index}/commits` - коммиты
+- `POST /repos/{owner}/{repo}/pulls/{index}/reviews` - создание ревью
+- `POST /repos/{owner}/{repo}/pulls/comments` - добавление комментария
+
+**GitHub API** - аналогичные endpoints через REST API v3
+**Bitbucket API** - через REST API 2.0
+
+### 4. Webhook обработчики
+
+**Gitea webhook payload:**
+```json
+{
+  "action": "opened" | "synchronized",
+  "pull_request": {
+    "id": 123,
+    "number": 42,
+    "title": "Fix bug",
+    ...
+  }
+}
+```
+
+**Обработка:**
+1. Валидация webhook secret
+2. Проверка, что репозиторий отслеживается
+3. Запуск LangGraph агента асинхронно
+4. Отправка WebSocket уведомлений
+
+### 5. REST API endpoints
+
+**Repositories:**
+- `GET /api/repositories` - список репозиториев
+- `POST /api/repositories` - добавить репозиторий
+- `PUT /api/repositories/{id}` - обновить репозиторий
+- `DELETE /api/repositories/{id}` - удалить репозиторий
+- `GET /api/repositories/{id}/webhook-url` - получить webhook URL
+
+**Reviews:**
+- `GET /api/reviews` - список ревью (с фильтрами)
+- `GET /api/reviews/{id}` - детали ревью
+- `GET /api/reviews/{id}/comments` - комментарии ревью
+- `POST /api/reviews/{id}/retry` - повторить ревью
+
+**Stats:**
+- `GET /api/stats/dashboard` - статистика для дашборда
+
+### 6. WebSocket
+
+**Endpoint:** `ws://localhost:8000/ws/reviews`
+
+**События:**
+```json
+{
+  "type": "review_started",
+  "review_id": 123,
+  "pr_id": 42
+}
+
+{
+  "type": "review_progress",
+  "review_id": 123,
+  "status": "analyzing",
+  "files_processed": 3,
+  "total_files": 10
+}
+
+{
+  "type": "review_completed",
+  "review_id": 123,
+  "comments_count": 5
+}
+```
+
+### 7. Frontend: Страницы
+
+**Dashboard** (`/`)
+- Статистика: всего ревью, активных PR, комментариев
+- График активности
+- Последние ревью
+
+**Repositories** (`/repositories`)
+- Таблица репозиториев
+- Кнопка "Add Repository"
+- Webhook URL для каждого
+- Статус (active/inactive)
+
+**Reviews** (`/reviews`)
+- Таблица всех ревью
+- Фильтры: по репозиторию, статусу, дате
+- Ссылки на детали
+
+**Review Detail** (`/reviews/:id`)
+- Информация о PR
+- Прогресс бар
+- Список сгенерированных комментариев
+- Real-time обновления
+
+### 8. Конфигурация
+
+**Backend (.env):**
+```env
+# Ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=codellama
+
+# Database
+DATABASE_URL=sqlite:///./review.db
+
+# Security
+SECRET_KEY=your-secret-key-here
+WEBHOOK_SECRET=your-webhook-secret
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+```
+
+**Frontend (.env):**
+```env
+VITE_API_URL=http://localhost:8000
+VITE_WS_URL=ws://localhost:8000
+```
+
+### 9. Развертывание
+
+**Требования:**
+- Python 3.11+
+- Node.js 18+
+- Ollama установлен и запущен
+
+**Запуск Backend:**
+```bash
+cd backend
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+**Запуск Frontend:**
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+**Настройка Ollama:**
+```bash
+ollama pull codellama
+ollama serve
+```
+
+### 10. Безопасность
+
+- API токены храним зашифрованными (Fernet)
+- Webhook secret для валидации запросов
+- CORS настроен только для frontend домена
+- Rate limiting на webhook endpoints
+- Валидация всех входных данных
+
+## Этапы разработки
+
+1. ✅ Создание структуры проекта
+2. ⏳ Backend: Модели и база данных
+3. ⏳ Backend: LangGraph агент
+4. ⏳ Backend: Интеграции с Git платформами
+5. ⏳ Backend: Webhook обработчики
+6. ⏳ Backend: REST API
+7. ⏳ Backend: WebSocket
+8. ⏳ Frontend: Базовая структура
+9. ⏳ Frontend: Компоненты и страницы
+10. ⏳ Frontend: Интеграция с Backend
+11. ⏳ Тестирование
+12. ⏳ Документация
+
+## Примечания
+
+- Gitea имеет приоритет в разработке
+- Агент работает в одном экземпляре (можно масштабировать через очереди позже)
+- Real-time обновления через WebSocket для UX
+- Модульная архитектура для легкого добавления новых платформ
+