readme

Author: iakkov

README.md

@@ -0,0 +1,244 @@
+# Тестовое задание Авито: Сервис назначения ревьюверов на Pull Request'ы
+
+## Описание
+
+Веб-сервис для автоматического назначения ревьюверов на Pull Request'ы внутри команд разработки. Сервис предоставляет REST API для управления командами, пользователями, Pull Request'ами и получения статистики по назначениям ревьюверов.
+
+## Функциональность
+
+### Управление командами
+- **POST /team/add** - Создание команды с участниками (создаёт/обновляет пользователей)
+- **GET /team/get?team_name={name}** - Получение информации о команде и её участниках
+
+### Управление пользователями
+- **POST /users/setIsActive** - Установка флага активности пользователя
+- **GET /users/getReview?user_id={id}** - Получение списка PR'ов, где пользователь назначен ревьювером
+
+### Управление Pull Request'ами
+- **POST /pullRequest/create** - Создание PR и автоматическое назначение до 2 ревьюверов из команды автора
+- **POST /pullRequest/merge** - Пометка PR как слитого (идемпотентная операция)
+- **POST /pullRequest/reassign** - Переназначение конкретного ревьювера на другого из его команды
+
+### Статистика
+- **GET /statistics** - Получение статистики назначений ревьюверов:
+  - Количество назначений по каждому пользователю
+  - Количество ревьюверов на каждый PR
+
+## Технологический стек
+
+- **Java 17** - язык программирования
+- **Spring Boot 3.2.5** - фреймворк для разработки веб-приложений
+- **PostgreSQL 15** - реляционная база данных
+- **Liquibase** - управление миграциями базы данных
+- **MapStruct 1.5.5** - генерация мапперов для преобразования объектов
+- **Lombok 1.18.32** - уменьшение boilerplate кода
+- **JUnit 5** - фреймворк для модульного и интеграционного тестирования
+- **Mockito** - библиотека для создания мок-объектов
+- **Testcontainers** - библиотека для интеграционных тестов с реальной базой данных
+- **Maven** - система сборки проекта
+- **Docker & Docker Compose** - контейнеризация и оркестрация
+
+## Архитектура проекта
+
+Проект организован в виде многомодульного Maven-проекта:
+
+```
+avito-test/
+├── avito-test-domain/     # Доменные модели, сущности JPA, репозитории
+├── avito-test-db/         # Миграции базы данных (Liquibase)
+├── avito-test-impl/       # Реализация бизнес-логики, контроллеры, сервисы, мапперы
+└── pom.xml                # Корневой POM файл
+```
+
+## Требования
+
+- **Java 17** или выше
+- **Maven 3.6+**
+- **Docker** и **Docker Compose** (для запуска через контейнеры)
+- **PostgreSQL 15** (если запускаете локально без Docker)
+
+## Установка и запуск
+
+### Запуск через Docker Compose (рекомендуется)
+
+1. Клонируйте репозиторий:
+```bash
+git clone <repository-url>
+cd avito-test
+```
+
+2. Запустите приложение через Docker Compose:
+```bash
+docker-compose up --build
+```
+
+Приложение будет доступно по адресу: `http://localhost:8080`
+
+### Локальный запуск
+
+1. Убедитесь, что PostgreSQL запущен и доступен:
+```bash
+# Создайте базу данных
+createdb avito_test
+
+# Или используйте Docker для PostgreSQL
+docker run -d \
+  --name avito-test-postgres \
+  -e POSTGRES_DB=avito_test \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -p 5432:5432 \
+  postgres:15-alpine
+```
+
+2. Настройте переменные окружения или отредактируйте `avito-test-impl/src/main/resources/application.yaml`:
+```yaml
+spring:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/avito_test
+    username: postgres
+    password: postgres
+```
+
+3. Соберите проект:
+```bash
+mvn clean install
+```
+
+4. Запустите приложение:
+```bash
+cd avito-test-impl
+mvn spring-boot:run
+```
+
+## API документация
+
+Полная документация API доступна в файле `openapi.yml` в формате OpenAPI 3.0.
+
+## Примеры использования API
+
+### Создание команды
+
+```bash
+curl -X POST http://localhost:8080/team/add \
+  -H "Content-Type: application/json" \
+  -d '{
+    "team_name": "backend",
+    "members": [
+      {
+        "user_id": "u1",
+        "username": "Alice",
+        "is_active": true
+      },
+      {
+        "user_id": "u2",
+        "username": "Bob",
+        "is_active": true
+      }
+    ]
+  }'
+```
+
+### Создание Pull Request
+
+```bash
+curl -X POST http://localhost:8080/pullRequest/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pull_request_id": "pr-1001",
+    "pull_request_name": "Add search",
+    "author_id": "u1"
+  }'
+```
+
+### Получение статистики
+
+```bash
+curl -X GET http://localhost:8080/statistics
+```
+
+## Тестирование
+
+Проект содержит полное покрытие тестами:
+
+### Модульные тесты
+- Тесты сервисов с использованием Mockito
+- Тесты контроллеров с использованием MockMvc
+
+### Интеграционные тесты
+- Тесты с реальной базой данных через Testcontainers
+- Полное покрытие всех API endpoints
+
+Запуск всех тестов:
+```bash
+mvn test
+```
+
+Запуск только интеграционных тестов:
+```bash
+mvn test -Dtest=*IntegrationTest
+```
+
+Запуск только модульных тестов:
+```bash
+mvn test -Dtest=*ServiceTest,*ControllerTest
+```
+
+**Примечание:** Для интеграционных тестов требуется запущенный Docker, так как используется Testcontainers.
+
+## База данных
+
+Схема базы данных управляется через Liquibase. Миграции находятся в модуле `avito-test-db/src/main/resources/db/changelog/`.
+
+### Структура базы данных
+
+- **teams** - таблица команд
+- **users** - таблица пользователей
+- **pull_requests** - таблица Pull Request'ов
+- **pull_request_reviewers** - связь многие-ко-многим между PR и ревьюверами
+
+## Бизнес-логика
+
+### Автоматическое назначение ревьюверов
+
+При создании Pull Request автоматически назначаются до 2 ревьюверов из команды автора:
+- Ревьюверы выбираются случайным образом из активных участников команды
+- Автор PR не может быть назначен ревьювером своего PR
+- Если в команде недостаточно кандидатов, назначается меньшее количество
+
+### Переназначение ревьювера
+
+При переназначении ревьювера:
+- Новый ревьювер выбирается из той же команды, что и старый
+- Новый ревьювер должен быть активным
+- Новый ревьювер не должен быть автором PR
+- Новый ревьювер не должен уже быть назначенным на этот PR
+- Нельзя переназначить ревьювера на PR, который уже слит (status = MERGED)
+
+### Обработка ошибок
+
+Сервис возвращает структурированные ошибки в формате:
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Описание ошибки"
+  }
+}
+```
+
+Коды ошибок:
+- `TEAM_EXISTS` - команда уже существует
+- `PR_EXISTS` - Pull Request с таким ID уже существует
+- `PR_MERGED` - попытка изменить уже слитый PR
+- `NOT_ASSIGNED` - ревьювер не назначен на PR
+- `NO_CANDIDATE` - нет доступных кандидатов для назначения
+- `NOT_FOUND` - ресурс не найден
+- 
+
+Это тестовое задание для Авито. Код предоставлен для демонстрации навыков разработки.
+
+## Автор
+
+Iakov Lysenko
+