diff --git a/main_dc/yalarba/api_tp/documentation/docs.md b/main_dc/yalarba/api_tp/documentation/docs.md new file mode 100644 index 0000000..5fd5ba7 --- /dev/null +++ b/main_dc/yalarba/api_tp/documentation/docs.md @@ -0,0 +1,303 @@ +# Документация REST API сервиса поиска мест отдыха + +## Общая информация + +### Технологический стек +- **Язык программирования**: Go 1.21+ +- **Веб-фреймворк**: Chi Router +- **ORM**: GORM +- **База данных**: PostgreSQL +- **Аутентификация**: JWT токены + +### Архитектура проекта +Проект построен по принципам чистой архитектуры с разделением на слои: +- **Repository** - работа с базой данных +- **Service** - бизнес-логика +- **Handler** - обработка HTTP запросов +- **Middleware** - промежуточные обработчики + +## Структура проекта +``` +api_tp/ +├── internal/ +│ ├── config/ # Конфигурация приложения +│ ├── handlers/ # HTTP обработчики +│ ├── middleware/ # Промежуточные обработчики +│ ├── models/ # Модели данных +│ ├── repository/ # Репозитории для работы с БД +│ ├── server/ # Конфигурация сервера +│ └── service/ # Бизнес-логика +├── pkg/ +│ └── database/ # Подключение к БД +└── main.go # Точка входа +``` + +## Текущие эндпоинты API + +### Версия API: v1 + +#### 1. Проверка здоровья сервиса +``` +GET /health +GET /v1/check +GET /v1/auth/check +GET /v1/api/users/check +``` +**Ответ:** +```json +{ + "status": "healthy", + "timestamp": "Tue, 02 Jan 2024 10:00:00 UTC" +} +``` + +#### 2. Аутентификация (публичные маршруты) + +##### Регистрация пользователя +``` +POST /v1/auth/register +``` +**Тело запроса (ожидается):** +```json +{ + "email": "user@example.com", + "password": "secure_password", + "name": "Имя пользователя" +} +``` + +##### Авторизация пользователя +``` +POST /v1/auth/login +``` +**Тело запроса (ожидается):** +```json +{ + "email": "user@example.com", + "password": "secure_password" +} +``` + +#### 3. Пользователи (защищенные маршруты - требуется JWT токен) + +##### Получение всех пользователей +``` +GET /v1/api/users/ +``` +**Заголовок:** +``` +Authorization: Bearer +``` + +##### Создание пользователя +``` +POST /v1/api/users/ +``` +**Заголовок:** +``` +Authorization: Bearer +``` + +##### Получение пользователя по ID +``` +GET /v1/api/users/{id} +``` +**Заголовок:** +``` +Authorization: Bearer +``` + +## Модель данных + +### Пользователь (UserT) +```go +type UserT struct { + ID uint `gorm:"primaryKey"` + Email string `gorm:"uniqueIndex;not null"` + Password string `gorm:"not null"` + Name string + CreatedAt time.Time + UpdatedAt time.Time +} +``` + +## Аутентификация +Защищенные маршруты требуют JWT токен, который должен передаваться в заголовке: +``` +Authorization: Bearer <ваш_jwt_токен> +``` + +## Запуск сервиса + +### Требования +1. Go 1.21 или выше +2. PostgreSQL 12+ +3. Установленные переменные окружения (детали в `config` пакете) + +### Запуск +```bash +go run main.go +``` + +Сервер запускается на порту, указанном в конфигурации (по умолчанию 8080). + +## Будущие реализации эндпоинтов + +### 1. Работа с местами отдыха + +#### Категории мест +``` +GET /v1/api/categories # Получение всех категорий +POST /v1/api/categories # Создание категории +GET /v1/api/categories/{id} # Получение категории по ID +PUT /v1/api/categories/{id} # Обновление категории +DELETE /v1/api/categories/{id} # Удаление категории +``` + +#### Сами места отдыха +``` +GET /v1/api/places # Получение всех мест +POST /v1/api/places # Создание места +GET /v1/api/places/{id} # Получение места по ID +PUT /v1/api/places/{id} # Обновление места +DELETE /v1/api/places/{id} # Удаление места +GET /v1/api/places/search # Поиск мест по параметрам +GET /v1/api/places/category/{id} # Места по категории +``` + +### 2. Отзывы и рейтинги + +``` +POST /v1/api/places/{id}/reviews # Добавление отзыва +GET /v1/api/places/{id}/reviews # Получение отзывов места +PUT /v1/api/reviews/{id} # Обновление отзыва +DELETE /v1/api/reviews/{id} # Удаление отзыва +POST /v1/api/places/{id}/rating # Добавление/обновление рейтинга +``` + +### 3. Избранное + +``` +GET /v1/api/user/favorites # Получение избранного пользователя +POST /v1/api/places/{id}/favorite # Добавление в избранное +DELETE /v1/api/places/{id}/favorite # Удаление из избранного +``` + +### 4. Фильтрация и поиск + +``` +GET /v1/api/places/filter # Расширенная фильтрация +``` +**Параметры запроса:** +- `category` - ID категории +- `min_price`, `max_price` - диапазон цен +- `rating` - минимальный рейтинг +- `location` - географическое положение +- `amenities` - удобства (wi-fi, парковка и т.д.) + +### 5. Административные функции + +``` +GET /v1/admin/users # Получение всех пользователей (админ) +PUT /v1/admin/users/{id}/status # Изменение статуса пользователя +GET /v1/admin/places/pending # Места ожидающие модерации +PUT /v1/admin/places/{id}/approve # Одобрение места +DELETE /v1/admin/places/{id} # Удаление места (админ) +``` + +### 6. Статистика и аналитика + +``` +GET /v1/api/analytics/popular-places # Популярные места +GET /v1/api/analytics/user-activity # Активность пользователя +GET /v1/admin/analytics/overview # Общая статистика (админ) +``` + +### 7. Геолокационные функции + +``` +GET /v1/api/places/nearby # Ближайшие места +POST /v1/api/location/suggest # Предложения по локации +``` + +### 8. Медиа-контент + +``` +POST /v1/api/places/{id}/photos # Добавление фотографий +DELETE /v1/api/photos/{id} # Удаление фотографии +GET /v1/api/places/{id}/photos # Получение фотографий места +``` + +## Планируемые модели данных + +### Место отдыха (Place) +```go +type Place struct { + ID uint `gorm:"primaryKey"` + Name string `gorm:"not null"` + Description string + CategoryID uint // Связь с категорией + Address string + Latitude float64 + Longitude float64 + PriceRange string // "низкий", "средний", "высокий" + Rating float64 `gorm:"default:0"` + CreatedBy uint // ID пользователя-создателя + CreatedAt time.Time + UpdatedAt time.Time +} +``` + +### Отзыв (Review) +```go +type Review struct { + ID uint `gorm:"primaryKey"` + PlaceID uint `gorm:"not null"` + UserID uint `gorm:"not null"` + Rating int `gorm:"check:rating >= 1 AND rating <= 5"` + Comment string + CreatedAt time.Time +} +``` + +### Категория (Category) +```go +type Category struct { + ID uint `gorm:"primaryKey"` + Name string `gorm:"uniqueIndex;not null"` + Description string + Icon string // URL иконки +} +``` + +## Безопасность и валидация + +1. **Валидация входных данных** на всех эндпоинтах +2. **Rate limiting** для предотвращения DDoS атак +3. **CORS** настройка для веб-клиентов +4. **Хеширование паролей** с использованием bcrypt +5. **JWT токены** с ограниченным временем жизни +6. **Ролевая модель** (пользователь, модератор, администратор) + +## Мониторинг и логирование + +1. **Structured logging** с использованием zap или logrus +2. **Метрики Prometheus** для мониторинга +3. **Health checks** расширенные +4. **Tracing** с использованием OpenTelemetry + +## Деплоймент + +### Docker +Планируется создание Dockerfile и docker-compose для развертывания: +- Приложение API +- PostgreSQL +- Redis (для кэширования) +- Nginx (как reverse proxy) + +### Kubernetes +Конфигурации для развертывания в Kubernetes кластере. + +--- + +*Примечание: Это предварительная документация. Реализация новых эндпоинтов будет сопровождаться обновлением документации.* \ No newline at end of file