From 47bbb4ebc4379768082914d2b1dfbee2d3a2f44c Mon Sep 17 00:00:00 2001 From: Primakov Alexandr Alexandrovich Date: Mon, 13 Oct 2025 14:20:23 +0300 Subject: [PATCH] docs: Add review events and versioning documentation --- docs/REVIEW_EVENTS_AND_VERSIONING.md | 264 +++++++++++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 docs/REVIEW_EVENTS_AND_VERSIONING.md diff --git a/docs/REVIEW_EVENTS_AND_VERSIONING.md b/docs/REVIEW_EVENTS_AND_VERSIONING.md new file mode 100644 index 0000000..7d054d1 --- /dev/null +++ b/docs/REVIEW_EVENTS_AND_VERSIONING.md @@ -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 + +``` + +### 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) +