From c7e7fb42a47668ec03e14448344246e9ed79c5b8 Mon Sep 17 00:00:00 2001
From: valitovgaziz <valitovgaziz@yandex.ru>
Date: Tue, 2 Dec 2025 19:34:58 +0500
Subject: [PATCH] 	new file:  
 main_dc/yalarba/api_es/documentation/docs.md add docs for easysite REST API
 service api_es

---
 main_dc/yalarba/api_es/documentation/docs.md | 259 +++++++++++++++++++
 1 file changed, 259 insertions(+)
 create mode 100644 main_dc/yalarba/api_es/documentation/docs.md

diff --git a/main_dc/yalarba/api_es/documentation/docs.md b/main_dc/yalarba/api_es/documentation/docs.md
new file mode 100644
index 0000000..98b2cb0
--- /dev/null
+++ b/main_dc/yalarba/api_es/documentation/docs.md
@@ -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 от паник
\ No newline at end of file