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):**
```json
{
  "email": "user@example.com",
  "password": "password123",
  "full_name": "Иван Иванов",
  "phone": "+79991234567",
  "city": "Москва"
}
```

#### Вход в систему
**POST /auth/login**  
*Получение токенов доступа*

**Тело запроса (AuthRequest):**
```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**Ответ (AuthResponse):**
```json
{
  "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):**
```json
{
  "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`:

```json
{
  "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 от паник