code-review-agent/docs/MASTER_TOKEN_FEATURE.md

# 🔑 Мастер токены для Git платформ

## 📋 Описание

Теперь можно настроить **мастер токены** в `.env` файле. Эти токены будут использоваться для всех репозиториев, где **не указан** собственный API токен.

---

## ⚙️ Как настроить

### 1. Добавьте в `.env`

```bash
# Master Git Tokens (optional)
MASTER_GITEA_TOKEN=your_gitea_token_here
MASTER_GITHUB_TOKEN=your_github_token_here
MASTER_BITBUCKET_TOKEN=your_bitbucket_token_here
```

### 2. Перезапустите backend

```bash
cd backend
./start.bat  # или ./start.sh на Linux/Mac
```

---

## 🎯 Как работает

### Логика выбора токена:

1. **Если у репозитория ЕСТЬ свой токен** → используется токен репозитория
2. **Если у репозитория НЕТ токена** → используется мастер токен из `.env`
3. **Если и мастер токен не настроен** → ошибка

### Приоритет:

```
Токен репозитория > Мастер токен > Ошибка
```

---

## 🔍 Примеры использования

### Вариант 1: Один токен для всех

**Сценарий:** Все ваши проекты находятся в одной Gitea инстанции

**.env:**
```bash
MASTER_GITEA_TOKEN=abc123xyz789
```

**Создание репозитория (без токена):**
```json
POST /api/repositories
{
  "name": "my-project",
  "platform": "GITEA",
  "url": "https://git.example.com/user/my-project"
  // api_token НЕ указан
}
```

✅ Будет использован `MASTER_GITEA_TOKEN`

---

### Вариант 2: Разные токены для разных проектов

**Сценарий:** У некоторых проектов особые требования к доступу

**.env:**
```bash
MASTER_GITEA_TOKEN=default_token_123
```

**Репозиторий 1 (использует мастер токен):**
```json
{
  "name": "project-a",
  "platform": "GITEA",
  "url": "https://git.example.com/user/project-a"
  // api_token НЕ указан → использует MASTER_GITEA_TOKEN
}
```

**Репозиторий 2 (свой токен):**
```json
{
  "name": "project-b",
  "platform": "GITEA",
  "url": "https://git.example.com/user/project-b",
  "api_token": "special_token_456"  // Указан свой токен
}
```

✅ `project-a` использует мастер токен
✅ `project-b` использует свой токен

---

### Вариант 3: Несколько платформ

**.env:**
```bash
MASTER_GITEA_TOKEN=gitea_token_123
MASTER_GITHUB_TOKEN=github_token_456
MASTER_BITBUCKET_TOKEN=bitbucket_token_789
```

**Репозитории:**
```json
// Gitea - использует MASTER_GITEA_TOKEN
{
  "platform": "GITEA",
  "url": "https://git.example.com/user/repo1"
}

// GitHub - использует MASTER_GITHUB_TOKEN
{
  "platform": "GITHUB",
  "url": "https://github.com/user/repo2"
}

// Bitbucket - использует MASTER_BITBUCKET_TOKEN
{
  "platform": "BITBUCKET",
  "url": "https://bitbucket.org/user/repo3"
}
```

---

## 🔒 Безопасность

### ⚠️ Важно:

- Мастер токены **НЕ шифруются** в `.env` (они должны быть читаемыми для приложения)
- Токены репозиториев **шифруются** перед сохранением в БД
- **НЕ коммитьте** `.env` файл в Git!
- Используйте `.env.example` как шаблон

### Права токенов:

Убедитесь что токены имеют необходимые права:

**Для Gitea/GitHub/Bitbucket:**
- ✅ Чтение репозитория
- ✅ Чтение PR
- ✅ Создание комментариев

---

## 📊 Логирование

При запуске ревью вы увидите какой токен используется:

```
📋 ИНФОРМАЦИЯ О PR
...
🔑 Используется мастер gitea токен
```

или

```
🔑 Используется проектный токен
```

---

## 🎨 Изменения в UI

### Форма создания репозитория:

**Было:**
```
API Token: [обязательное поле]
```

**Стало:**
```
API Token: [необязательное поле]
Подсказка: Оставьте пустым чтобы использовать мастер токен
```

---

## 📝 Примеры из логов

### С мастер токеном:

```
📤 Публикация ревью в Gitea PR #5
   Комментариев: 4
   🔑 Используется мастер gitea токен
   ✅ Комментарий опубликован!
```

### С проектным токеном:

```
📤 Публикация ревью в Gitea PR #5
   Комментариев: 4
   🔑 Используется проектный токен
   ✅ Комментарий опубликован!
```

### Ошибка (токен не настроен):

```
❌ ERROR: API токен не указан для репозитория my-project
и мастер токен для gitea не настроен в .env (MASTER_GITEA_TOKEN)
```

---

## 🔧 Миграция базы данных

Поле `api_token` в таблице `repositories` теперь **nullable**:

**Старая схема:**
```sql
api_token VARCHAR NOT NULL
```

**Новая схема:**
```sql
api_token VARCHAR NULL
```

⚠️ **Если у вас уже есть репозитории:**
- Они продолжат работать со своими токенами
- Новые репозитории можно создавать без токена

---

## 🧪 Как протестировать

### 1. Настройте мастер токен в `.env`

```bash
MASTER_GITEA_TOKEN=your_token_here
```

### 2. Создайте репозиторий БЕЗ токена

```bash
curl -X POST http://localhost:8000/api/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-repo",
    "platform": "GITEA",
    "url": "https://git.example.com/user/test-repo"
  }'
```

### 3. Запустите ревью

Кнопка "🔍 Проверить сейчас"

### 4. Проверьте логи

Должно быть: `🔑 Используется мастер gitea токен`

---

## ✅ Преимущества

1. **Удобство** - не нужно указывать токен для каждого репозитория
2. **Гибкость** - можно переопределить токен для конкретного репозитория
3. **Безопасность** - проектные токены все еще шифруются
4. **Масштабируемость** - легко добавлять много репозиториев

---

## 📁 Измененные файлы

- `backend/app/config.py` - добавлены настройки мастер токенов
- `backend/app/models/repository.py` - `api_token` теперь nullable
- `backend/app/schemas/repository.py` - `api_token` опциональный
- `backend/app/api/repositories.py` - логика выбора токена
- `backend/app/agents/reviewer.py` - логика выбора токена
- `backend/.env.example` - пример конфигурации

---

## 🎉 Готово!

Теперь вы можете:
- ✅ Использовать один токен для всех репозиториев
- ✅ Переопределять токен для конкретных репозиториев
- ✅ Легко масштабировать систему

**Попробуйте!** 🚀