ADD requirements.md

requirements.md

@@ -0,0 +1,85 @@
+# Требования к боту 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 — единое время для всей команды (настраивается глобально).
+