tp/main_dc/yalarba/api_es/documentation/docs.md

Документация REST API сервиса "Travel Platform"

Общая информация

API сервиса для управления туристическими объектами (отели, санатории, достопримечательности и др.) с системой аутентификации пользователей, отзывами и фильтрацией.

Базовый URL

http://localhost:8080 (или другой хост/порт в зависимости от конфигурации)

---

Модели данных

Пользователь (User)

Поля:

• id - уникальный идентификатор
• email - электронная почта (уникальный)
• password_hash - хеш пароля
• full_name, first_name, last_name - имя пользователя
• phone, city - контактная информация
• organization_* - бизнес-данные для владельцев
• is_active, is_verified, role - статус и права доступа

Объект (Object)

Типы объектов:

• hotel - отель
• sanatorium - санаторий
• guest_house - гостевой дом
• tour - тур
• restaurant - ресторан
• museum - музей
• landmark - достопримечательность
• event - мероприятие
• route - маршрут

Статусы объектов:

• draft - черновик
• moderation - на модерации
• active - активен
• inactive - неактивен
• rejected - отклонен

Отзыв (Review)

• Оценка от 1 до 5 звезд
• Текстовый отзыв
• Связь с объектом и автором

---

Аутентификация и авторизация

Система токенов:

• Access Token - для доступа к защищенным ресурсам
• Refresh Token - для обновления access token
• Token Type: Bearer
• Токены передаются в заголовке Authorization: Bearer <token>

Роли пользователей:

1. user - обычный пользователь
2. moderator - модератор
3. admin - администратор

---

Эндпоинты API

1. Проверка работоспособности

GET /health
GET /check
Проверка доступности сервиса

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

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

POST /auth/register
Создание нового аккаунта

Тело запроса (UserRegisterRequest):

{
  "email": "user@example.com",
  "password": "password123",
  "full_name": "Иван Иванов",
  "phone": "+79991234567",
  "city": "Москва"
}

Вход в систему

POST /auth/login
Получение токенов доступа

Тело запроса (AuthRequest):

{
  "email": "user@example.com",
  "password": "password123"
}

Ответ (AuthResponse):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "full_name": "Иван Иванов"
    // ... остальные поля UserResponse
  }
}

Обновление токена

POST /auth/refresh
Получение нового access token по refresh token

Тело запроса (RefreshTokenRequest):

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Выход из системы

POST /auth/logout
Инвалидация токенов

3. Профиль пользователя

Получение профиля

GET /users/profile
Требуется аутентификация
Получение данных текущего пользователя

Обновление профиля

PUT /users/profile
Требуется аутентификация
Обновление данных пользователя

4. Управление пользователями (Admin)

Список пользователей

GET /users
Требуется роль admin
Получение списка всех пользователей

Получение пользователя по ID

GET /users/{id}
Требуется роль admin
Получение данных конкретного пользователя

---

Фильтрация и пагинация

Для эндпоинтов списков объектов поддерживается фильтрация через ObjectFilter:

Параметры запроса:

• search - текстовый поиск
• type - тип объекта (hotel, sanatorium и т.д.)
• city - город
• min_price, max_price - диапазон цен
• min_rating - минимальный рейтинг
• status - статус объекта
• owner_id - ID владельца
• page - номер страницы (начинается с 1)
• page_size - количество элементов на странице (1-100)
• sort_by - поле сортировки (title, price, rating, city, created_at)
• sort_order - порядок сортировки (asc, desc)

Пример запроса:

GET /objects?city=Москва&min_price=1000&max_price=5000&page=1&page_size=20&sort_by=price&sort_order=asc

---

Формат ответа с пагинацией

Для списков возвращается PaginatedResponse:

{
  "data": [...], // массив объектов
  "total": 150,  // общее количество
  "page": 1,     // текущая страница
  "page_size": 20, // элементов на странице
  "total_pages": 8  // всего страниц
}

---

Обработка ошибок

Сервис использует стандартные HTTP статусы:

• 200 - успешный запрос
• 201 - создан новый ресурс
• 400 - ошибка валидации
• 401 - неавторизован
• 403 - доступ запрещен
• 404 - ресурс не найден
• 500 - внутренняя ошибка сервера

---

Следующие шаги (планируемые эндпоинты)

На основе моделей данных ожидаются следующие API:

Управление объектами:

• GET /objects - список объектов с фильтрацией
• GET /objects/{id} - получение объекта
• POST /objects - создание объекта (требуется аутентификация)
• PUT /objects/{id} - обновление объекта
• DELETE /objects/{id} - удаление объекта

Управление отзывами:

• GET /objects/{id}/reviews - отзывы объекта
• POST /reviews - создание отзыва
• PUT /reviews/{id} - обновление отзыва
• DELETE /reviews/{id} - удаление отзыва

Модерация:

• GET /moderation/objects - объекты на модерации
• POST /moderation/objects/{id}/approve - утвердить объект
• POST /moderation/objects/{id}/reject - отклонить объект

Отчеты и аналитика:

• GET /reports/popular-objects - популярные объекты
• GET /reports/user-activity - активность пользователей
• GET /reviews/revenue - аналитика доходов

---

Технические детали

База данных:

• Используется GORM (Go ORM)
• Поддерживаются миграции
• Soft delete для основных сущностей

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

• Структурированное логирование через Zap
• Логирование маршрутов при запуске
• Middleware для логирования запросов

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

• Централизованная конфигурация через config.Config
• Поддержка разных окружений

Middleware:

• Аутентификация (AuthMiddleware)
• Авторизация по ролям (AdminMiddleware)
• Логирование
• Recovery от паник