# План создания 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
- Модульная архитектура для легкого добавления новых платформ