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