docs: Add review events and versioning documentation
This commit is contained in:
Primakov Alexandr Alexandrovich
parent
2db1225618
commit
47bbb4ebc4
264
docs/REVIEW_EVENTS_AND_VERSIONING.md
Normal file
264
docs/REVIEW_EVENTS_AND_VERSIONING.md
Normal file
@ -0,0 +1,264 @@
|
||||
# Персистентные события Review и система версионирования
|
||||
|
||||
## Что добавлено
|
||||
|
||||
### 1. Сохранение событий review в БД
|
||||
|
||||
#### Backend
|
||||
|
||||
- ✅ Модель `ReviewEvent` для хранения событий процесса review
|
||||
- ✅ API endpoint `/api/reviews/{review_id}/events` для получения событий
|
||||
- ✅ Автоматическое сохранение всех событий в БД при обработке review
|
||||
- ✅ Связь с моделью Review через relationship
|
||||
|
||||
**Структура события:**
|
||||
```python
|
||||
class ReviewEvent:
|
||||
id: int
|
||||
review_id: int
|
||||
event_type: str # agent_step, llm_message, review_started, etc.
|
||||
step: Optional[str] # fetch_pr_info, analyze_files, etc.
|
||||
message: Optional[str]
|
||||
data: Optional[Dict]
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
#### Frontend
|
||||
|
||||
- ✅ Компонент `ReviewStream` загружает исторические события из БД
|
||||
- ✅ События отображаются даже после завершения review
|
||||
- ✅ При обновлении страницы события восстанавливаются
|
||||
|
||||
**Использование:**
|
||||
```tsx
|
||||
<ReviewStream reviewId={reviewId} />
|
||||
```
|
||||
|
||||
### 2. Показ версии бэкенда
|
||||
|
||||
#### Backend
|
||||
|
||||
- ✅ Файл `backend/VERSION` с текущей версией (semver format)
|
||||
- ✅ API endpoint `/api/version` для получения версии
|
||||
|
||||
#### Frontend
|
||||
|
||||
- ✅ Компонент `Footer` показывает версию внизу страницы
|
||||
- ✅ Автоматическое обновление версии каждые 5 минут
|
||||
- ✅ Кеширование версии для производительности
|
||||
|
||||
### 3. Автоповышение версии (Git Hook)
|
||||
|
||||
#### Скрипты
|
||||
|
||||
**`bump_version.sh`** - Скрипт повышения версии:
|
||||
```bash
|
||||
bash bump_version.sh patch # 0.1.0 → 0.1.1
|
||||
bash bump_version.sh minor # 0.1.0 → 0.2.0
|
||||
bash bump_version.sh major # 0.1.0 → 1.0.0
|
||||
```
|
||||
|
||||
**`.git-hooks/pre-commit`** - Pre-commit hook:
|
||||
- Автоматически вызывается при каждом коммите
|
||||
- Анализирует изменения в `backend/` директории
|
||||
- Повышает версию на основе типа коммита
|
||||
|
||||
#### Правила версионирования
|
||||
|
||||
Версия повышается автоматически на основе префикса коммита:
|
||||
|
||||
| Префикс коммита | Изменение версии | Пример |
|
||||
|-----------------|------------------|---------|
|
||||
| `feat:` или `feature:` | MINOR | 0.1.0 → 0.2.0 |
|
||||
| `fix:` или `bugfix:` | PATCH | 0.1.0 → 0.1.1 |
|
||||
| `BREAKING:` или `major:` | MAJOR | 0.1.0 → 1.0.0 |
|
||||
| Остальные | PATCH | 0.1.0 → 0.1.1 |
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
git commit -m "feat: Add new feature" # 0.1.0 → 0.2.0
|
||||
git commit -m "fix: Fix critical bug" # 0.1.0 → 0.1.1
|
||||
git commit -m "BREAKING: Remove old API" # 0.1.0 → 1.0.0
|
||||
git commit -m "docs: Update README" # 0.1.0 → 0.1.1
|
||||
```
|
||||
|
||||
## Установка Git Hook
|
||||
|
||||
Чтобы активировать автоповышение версии:
|
||||
|
||||
```bash
|
||||
# Из корня проекта
|
||||
git config core.hooksPath .git-hooks
|
||||
|
||||
# Сделать hook исполняемым (Linux/Mac)
|
||||
chmod +x .git-hooks/pre-commit
|
||||
```
|
||||
|
||||
На Windows Git Bash автоматически обрабатывает права выполнения.
|
||||
|
||||
## Отключение hook
|
||||
|
||||
Если нужно закоммитить без повышения версии:
|
||||
|
||||
```bash
|
||||
# Одноразово
|
||||
git commit --no-verify -m "Your message"
|
||||
|
||||
# Полностью отключить
|
||||
git config core.hooksPath .git/hooks
|
||||
```
|
||||
|
||||
## Миграция БД
|
||||
|
||||
Для добавления таблицы `review_events`:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python migrate.py
|
||||
```
|
||||
|
||||
Или вручную:
|
||||
```bash
|
||||
sqlite3 backend/review.db < backend/migrations/add_review_events.sql
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Получить события review
|
||||
|
||||
```http
|
||||
GET /api/reviews/{review_id}/events
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"review_id": 1,
|
||||
"event_type": "agent_step",
|
||||
"step": "fetch_pr_info",
|
||||
"message": "Получение информации о PR...",
|
||||
"data": {},
|
||||
"created_at": "2025-10-13T10:30:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Получить версию бэкенда
|
||||
|
||||
```http
|
||||
GET /api/version
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"version": "0.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
├── backend/
|
||||
│ ├── VERSION # Файл версии
|
||||
│ ├── migrations/
|
||||
│ │ └── add_review_events.sql # Миграция для таблицы событий
|
||||
│ ├── app/
|
||||
│ │ ├── models/
|
||||
│ │ │ └── review_event.py # Модель события
|
||||
│ │ ├── schemas/
|
||||
│ │ │ └── review_event.py # Схемы события
|
||||
│ │ └── api/
|
||||
│ │ └── reviews.py # API endpoints
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── ReviewStream.tsx # Компонент стриминга
|
||||
│ │ │ └── Footer.tsx # Футер с версией
|
||||
│ │ └── api/
|
||||
│ │ └── client.ts # API клиент
|
||||
├── .git-hooks/
|
||||
│ ├── pre-commit # Pre-commit hook
|
||||
│ └── README.md # Документация hooks
|
||||
├── bump_version.sh # Скрипт повышения версии
|
||||
└── docs/
|
||||
└── REVIEW_EVENTS_AND_VERSIONING.md # Эта документация
|
||||
```
|
||||
|
||||
## Обновление на сервере
|
||||
|
||||
После деплоя:
|
||||
|
||||
1. Применить миграции:
|
||||
```bash
|
||||
cd ~/code-review-agent/backend
|
||||
python migrate.py
|
||||
```
|
||||
|
||||
2. Перезапустить сервис:
|
||||
```bash
|
||||
sudo systemctl restart ai-review
|
||||
```
|
||||
|
||||
3. Проверить версию:
|
||||
```bash
|
||||
curl http://localhost:8000/api/version
|
||||
```
|
||||
|
||||
## Проверка работы
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
# Проверить что таблица создана
|
||||
sqlite3 backend/review.db ".tables"
|
||||
# Должна быть таблица review_events
|
||||
|
||||
# Проверить версию
|
||||
cat backend/VERSION
|
||||
# Должна быть версия в формате X.Y.Z
|
||||
|
||||
# Проверить API
|
||||
curl http://localhost:8000/api/version
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
1. Откройте приложение в браузере
|
||||
2. Внизу страницы должна быть видна версия: `Backend v0.1.0`
|
||||
3. Откройте страницу review
|
||||
4. Компонент "Процесс Review" должен показывать события даже после завершения
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Git hook не работает
|
||||
|
||||
```bash
|
||||
# Проверить настройку
|
||||
git config core.hooksPath
|
||||
|
||||
# Переустановить
|
||||
git config core.hooksPath .git-hooks
|
||||
|
||||
# На Windows может потребоваться Git Bash
|
||||
```
|
||||
|
||||
### События не сохраняются
|
||||
|
||||
```bash
|
||||
# Проверить что таблица существует
|
||||
sqlite3 backend/review.db "SELECT * FROM review_events LIMIT 1;"
|
||||
|
||||
# Применить миграцию
|
||||
python backend/migrate.py
|
||||
```
|
||||
|
||||
### Версия не отображается на UI
|
||||
|
||||
1. Проверьте что файл `backend/VERSION` существует
|
||||
2. Проверьте endpoint: `curl http://localhost:8000/api/version`
|
||||
3. Проверьте консоль браузера на ошибки
|
||||
4. Очистите кеш браузера (Ctrl+F5)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user