Backend Trainee Assignment - Сервис ПВЗ

Тестовое задание для прохождения отбора на стажировку в Авито (Весна 2025).

Проект сервиса для работы с Пунктами Выдачи Заказов (ПВЗ) для Авито, реализуемый с использованием принципов Чистой Архитектуры на Go.

Структура проекта

Проект следует принципам Чистой Архитектуры с четкими слоями:

• Entities: Бизнес-объекты и правила
• Use Cases: Бизнес-логика приложения
• Interfaces: Адаптеры между слоями
• Infrastructure: Реализация всей инфраструктуры

🚀 Быстрый старт

1. Клонируй репозиторий:

git clone https://github.com/nikborovets/backend-trainee-assignment-spring-2025.git
cd backend-trainee-assignment-spring-2025

2. Создай файл .env (пример конфигурации: .env.example).

make setup-env

3. Запусти всё через Docker:

docker compose up --build -d

4. Проверь, что сервис жив:

curl -i http://localhost:8080/ping
# Должно вернуть {"message":"pong"}

5. Swagger/OpenAPI:
   Описание API — в файле swagger.yaml (можно открыть в Swagger Editor).

6. Получить тестовый JWT:

# Для модератора (нужен для создания ПВЗ):
curl -X POST http://localhost:8080/dummyLogin -H 'Content-Type: application/json' -d '{"role":"moderator"}'

# Для сотрудника ПВЗ (нужен для работы с приёмками и товарами):
curl -X POST http://localhost:8080/dummyLogin -H 'Content-Type: application/json' -d '{"role":"pvz_staff"}'

# Сохрани полученный токен:
export TOKEN="полученный_токен"

7. Примеры запросов:

# Создать ПВЗ (нужен токен модератора):
curl -X POST http://localhost:8080/pvz/ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"city":"Москва"}'
# Ответ: {"id":"<PVZ_ID>", ...}
# Сохрани ID ПВЗ для следующих запросов

# Получить список ПВЗ:
curl -X GET http://localhost:8080/pvz/ -H "Authorization: Bearer $TOKEN"

# Создать приёмку (нужен токен сотрудника ПВЗ):
curl -X POST http://localhost:8080/receptions/ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"pvzId":"<PVZ_ID>"}'
# Ответ: {"id":"<RECEPTION_ID>", ...}

# Добавить товар (нужен токен сотрудника ПВЗ):
curl -X POST http://localhost:8080/products/ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"type":"электроника","pvzId":"<PVZ_ID>"}'
# Ответ: {"id":"<PRODUCT_ID>", ...}

# Закрыть приёмку (нужен токен сотрудника ПВЗ):
curl -X POST http://localhost:8080/pvz/<PVZ_ID>/close_last_reception -H "Authorization: Bearer $TOKEN"
# Ответ: {"id":"<RECEPTION_ID>","status":"close", ...}

# Удалить последний товар (нужен токен сотрудника ПВЗ):
curl -X POST http://localhost:8080/pvz/<PVZ_ID>/delete_last_product -H "Authorization: Bearer $TOKEN"

8. Остановить сервис:

docker compose down

Порты

• HTTP API: 8080
• gRPC: 3000
• Prometheus: 9000

🚀 Запуск приложения

make docker-build    # Собрать образы
make docker-up       # Запустить базу, миграции и приложение
make docker-logs     # Смотреть логи приложения
make docker-down     # Остановить и удалить контейнеры

🧪 Запуск тестов

make docker-build-test   # Собрать образ для тестов (нужно один раз или после изменений)
make docker-test         # Запустить тесты в Docker

Запуск тестов и покрытие

# Запуск всех тестов с подробным выводом
go test -v ./test/...
go test -v -count=1 ./test/...

# Покрытие production-кода (всех пакетов internal) тестами из test/*
go test -coverpkg=./internal/... ./test/...

# Генерация отчета о покрытии
go test -coverpkg=./internal/... -coverprofile=cover.out ./test/...
go tool cover -func=cover.out

# Открыть отчет в браузере
go tool cover -html=cover.out

Дополнительная информация

• Все переменные окружения и настройки — в .env
• Для CI/CD, Prometheus, gRPC — см. отдельные секции в README
• Если что-то не работает — смотри логи: docker compose logs --tail=100 app
• Для Swagger UI: https://editor.swagger.io/ (загрузи swagger.yaml)

Прогресс выполнения

Базовый функционал

• Настройка проекта

  • Инициализация Git-репозитория
  • Создание .gitignore
  • Создание PUML-диаграммы архитектуры проекта (ЧА)
  • Настройка структуры проекта в соответствии с чистой архитектурой
    • Создание директорий: cmd/service, internal/entities, internal/usecases, internal/interfaces, internal/infrastructure, configs, test
    • Инициализация go.mod (Go module)
    • Настройка структуры проекта в соответствии с чистой архитектурой
  • Настройка Docker и Docker Compose

• Domain Layer (Entities)

  • Определение моделей данных (User, PVZ, Reception, Product)
  • Определение правил бизнес-логики

• Use Cases

  • CreatePVZ (создание ПВЗ)
  • CreateReception (создание приёмки)
  • AddProduct (добавление товара)
  • DeleteLastProductUseCase (удаление последнего товара LIFO)
  • CloseReceptionUseCase (закрытие приёмки)
  • ListPVZsUseCase (листинг ПВЗ с фильтрами)
  • DummyLoginUseCase (выдача токена по роли, без пароля)
  • LoginUseCase (логин по email+пароль)
  • RegisterUseCase (регистрация пользователя)
  • Получение данных с фильтрацией (есть фильтры по дате и пагинация в /pvz)

• Interfaces Layer

  • Определение репозиториев (интерфейсы)
  • Определение контроллеров
  • Определение DTO
    • Реализованы все основные DTO: UserDTO, PVZDTO, FullPVZDTO, ReceptionDTO, ProductDTO, ReceptionWithProductsDTO, RegisterRequest, LoginRequest, ListParams, AddProductRequest (internal/interfaces/dto.go)
    • Все репозиторные интерфейсы: UserRepository, PVZRepository, ReceptionRepository, ProductRepository (internal/interfaces/repository.go)
    • Все контроллеры: AuthController, PVZController, ReceptionController, ProductController (internal/interfaces/*_controller.go) — строго по .puml и ТЗ

• Infrastructure Layer

  • Базы данных
    • Настройка PostgreSQL (миграции, FK, индексы, ограничения)
    • Реализованы все PG-репозитории: User, PVZ, Reception, Product (internal/infrastructure/repositories)
    • Используется Squirrel, без ORM, только чистый SQL
    • Интеграционные тесты для каждого репозитория (test/infrastructure/repositories), покрытие >75%
    • Структура файлов: всё разнесено по подпапкам, нет каши
  • HTTP сервер
    • Настройка HTTP сервера (Gin)
    • Реализация эндпоинтов авторизации
      • POST /dummyLogin
      • POST /register
      • POST /login
    • Реализация эндпоинтов ПВЗ
      • POST /pvz
      • GET /pvz
      • POST /pvz/{pvzId}/close_last_reception
      • POST /pvz/{pvzId}/delete_last_product
    • Реализация эндпоинтов приемки
      • POST /receptions
    • Реализация эндпоинтов товаров
      • POST /products

• Тесты

  • Unit-тесты (покрытие > 75%)
  • Интеграционный тест сценария работы с ПВЗ и товарами

Дополнительные задания

• Авторизация

  • Полная реализация авторизации (регистрация и логин)

• gRPC

  • Настройка gRPC сервера
  • Реализация метода GetPVZList

• Метрики Prometheus

  • Сбор технических метрик (количество запросов, время ответа)
  • Сбор бизнес-метрик (количество ПВЗ, приемок, товаров)
  • Настройка эндпоинта /metrics

• Логирование

  • Настройка централизованного логирования
  • Логирование ключевых операций

• Кодогенерация

  • Настройка генерации DTO по OpenAPI схеме

Общий прогресс

• Базовый функционал - 100% завершен
• Дополнительные задания - 1/5 завершено (реализована авторизация)