# Требования к боту CodeReview

> Составлено на основе встречи 18.02.2026

---

## 1. Назначение

Telegram-бот для автоматизации процесса Code Review: назначение ревьюеров, уведомления и балансировка нагрузки внутри команды.

---

## 2. Функциональные требования

### 2.1 Регистрация пользователей

- Каждый участник команды должен самостоятельно зарегистрироваться в боте (написать `/start` или аналогичную команду), чтобы бот мог отправлять личные сообщения.
- При регистрации пользователь указывает свой **email-адрес из Git** — это необходимо для связки аккаунта Gitea с аккаунтом Telegram.
- Без регистрации бот не может писать пользователю в ЛС (ограничение Telegram API).

### 2.2 Автоматическое назначение ревьюеров

- При создании Pull Request (PR) бот автоматически назначает ревьюера, если он не был указан вручную.
- Автор PR **исключается** из пула кандидатов.
- Участники, указавшие период недоступности, также исключаются из пула на это время.
- Если бот назначил ревьюера (а не пользователь вручную), на PR автоматически **вешается лейбл** (например, `auto-assigned`).

### 2.3 Уведомления

- Бот отправляет уведомления **в личные сообщения**, а не в общий чат, чтобы не создавать шум.
- Уведомления отправляются в следующих случаях:
  - назначение ревьюером на PR;
  - появление новых комментариев в PR, где пользователь является автором или ревьюером;
  - добавление новых коммитов в PR, назначенный на пользователя (например, после запроса правок);
  - изменение статуса PR (approved, changes requested, merged, closed).

### 2.4 Балансировка нагрузки

- Бот ведёт счётчик активных (открытых) ревью для каждого участника.
- При выборе ревьюера назначается тот, у кого наименьшее количество активных ревью.
- Если несколько участников имеют одинаковую нагрузку — выбор между ними происходит **случайно**.
- Автор PR и недоступные участники в расчёт не включаются.

### 2.5 Управление доступностью

- Пользователь может указать период недоступности через команду бота (например, `/away 2026-03-01 2026-03-10`).
- В этот период пользователь не получает назначений на ревью.
- По истечении периода пользователь автоматически возвращается в пул.

### 2.6 Напоминания (пинги)

- Бот автоматически напоминает ревьюеру о висящих (не закрытых) PR.
- Каждый пользователь **самостоятельно настраивает время напоминаний** через команду бота (например, `/reminder 09:00`).
- Периодичность: ежедневно, пока PR не закрыт или не смержен.

---

## 3. Интеграции

| Интеграция | Описание |
|---|---|
| Gitea API | Получение событий PR (создание, комментарии, статус), назначение ревьюеров и простановка лейблов через API |
| Telegram Bot API | Отправка личных сообщений пользователям |

- Токены и доступ к Gitea API предоставляет Андрей Епифанцев.

---

## 4. Нефункциональные требования

- Бот пишет только в **личные сообщения**, общий чат не используется.
- Бот должен корректно обрабатывать ситуации, когда пользователь не зарегистрирован (логировать, не падать).
- Статус задачи: **side quest** — разрабатывается в свободное время.

---

## 5. MVP (минимально жизнеспособный продукт)

Для первого запуска достаточно:

1. Регистрация пользователя в боте с указанием Gitea email.
2. Webhook от Gitea: при создании PR без ревьюера — назначить участника с наименьшим числом активных ревью (исключая автора; при равной нагрузке — случайный выбор).
3. Уведомление назначенного ревьюера в Telegram ЛС.
4. Напоминание о висящих PR — единое время для всей команды (настраивается глобально).