Booking Service API

Сервис бронирования переговорок с REST API.

Описание

Сервис позволяет администраторам создавать переговорки и настраивать расписание их доступности, а пользователям - просматривать доступные слоты и создавать/отменять брони.

Стек технологий

• Язык: Go 1.26
• Веб-фреймворк: Gin
• База данных: PostgreSQL (jackc/pgx/v5)
• Авторизация: JWT
• Конфигурация: .env и config/config.yaml (cleanenv, godotenv)
• Документация: Swagger (swaggo)
• Миграции: migrate
• Тестирование: testify

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

.
├── cmd/
│   ├── app/                    # Точка входа приложения
│   └── db_seed/                # Наполнение БД тестовыми данными
├── config/                     # Конфигурация
├── db/
│   ├── migrations/             # SQL миграции
│   └── queries/                # SQL запросы (sqlc)
├── docs/                       # Сгенерированная Swagger документация
├── internal/
│   ├── app/                    # Инициализация приложения
│   ├── controller/             # HTTP контроллеры
│   │   └── restapi/            # REST API
│   │       ├── dto/            # Data Transfer Objects
│   │       ├── handler/        # Handlers
│   │       └── middleware/     # Middleware (JWT, CORS, Role)
│   ├── deps/                   # Зависимости
│   ├── entity/                 # Сущности предметной области
│   ├── errs/                   # Кастомные ошибки
│   ├── repo/                   # Репозитории (доступ к БД)
│   └── usecase/                # Бизнес-логика
├── pkg/
│   ├── httpserver/             # HTTP сервер
│   ├── logger/                 # Логирование
│   ├── postgres/               # Подключение к PostgreSQL
│   ├── timeonly/               # Утилиты для работы со временем
│   └── utils/                  # Общие утилиты (JWT, криптография, валидация)
└── tests/
    ├── integration/            # Интеграционные тесты
    └── mocks/                  # Mock-и для тестов

Требования

• Docker и Docker Compose
• Go 1.26+

Конфигурация

Параметры настраиваются через переменные окружения .env или файл config/config.yaml:

• POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_SSL_MODE - подключение к БД

• JWT_SECRET - секрет для подписи JWT токенов

• CONFIG_PATH - путь к файлу конфигурации

• MIGRATIONS_PATH - путь к миграциям

• POSTGRES_EXTERNAL_PORT - внешний порт Postgres контейнера

• EXTERNAL_API_PORT - внешний порт api контейнера

Доступные команды Make

make help  # Показать все доступные команды

Запуск

Docker Compose (рекомендуемый)

# Запуск всех сервисов
docker compose up --build

# Или через Makefile
make up

• Сервис доступен на localhost:8080.
• Swagger документация доступен на http://localhost:8080/swagger/index.html

Локальная разработка

# Установка зависимостей
go mod tidy

# Установка инструментов
make install-tools

# Запуск приложения
make run

# С горячей перезагрузкой (air)
make run-live

Наполнение БД тестовыми данными

make seed

API Endpoints

Аутентификация

• POST /dummyLogin - Получение тестового JWT токена (обязательно)
• POST /register - Регистрация пользователя (доп. задание)
• POST /login - Вход по email/паролю (доп. задание)

Переговорки (Rooms)

• GET /rooms/list - Список переговорок
• POST /rooms/create - Создать переговорку (admin only)

Расписание (Schedules)

• POST /rooms/{roomId}/schedule/create - Создать расписание (admin only, один раз)

Слоты (Slots)

• GET /rooms/{roomId}/slots/list?date=YYYY-MM-DD - Доступные слоты для бронирования

Брони (Bookings)

• POST /bookings/create - Создать бронь (user only)
• GET /bookings/list - Все брони с пагинацией (admin only)
• GET /bookings/my - Мои брони на будущее (user only)
• POST /bookings/{bookingId}/cancel - Отменить бронь (user only)

Система

• GET /_info - Health check (всегда 200)

Авторизация

Для тестирования используйте /dummyLogin:

# Получить токен admin
curl -X POST http://localhost:8080/dummyLogin \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

# Получить токен user
curl -X POST http://localhost:8080/dummyLogin \
  -H "Content-Type: application/json" \
  -d '{"role": "user"}'

Используйте полученный токен в заголовке Authorization: Bearer <token>.

Тесты

# Юнит-тесты
make test

# Интеграционные тесты
make test-integration

# Все тесты с покрытием
make test-all

Генерация документации

# Swagger
make swag-gen-docs

# SQL кодогенерация (sqlc)
make sqlc-gen

Линтинг

make lint
make lint-fix  # С авто-исправлением

Формирование слотов

Используется гибридный режим: слоты создаются заранее при добавлении расписания на 7 дней вперёд, а также могут генерироваться на лету при запросе, если запрошенная дата выходит за пределы доступных слотов.

Идемпотентность отмены брони

Повторная отмена уже отменённой брони возвращает 200 с актуальным состоянием, не считаясь ошибкой. Это реализовано на уровне usecase.