new file: main_dc/yalarba/api_es/documentation/docs.md
add docs for easysite REST API service api_es
This commit is contained in:
@@ -0,0 +1,259 @@
|
|||||||
|
# Документация 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 от паник
|
||||||
Reference in New Issue
Block a user