tp/main_dc/yalarba/api_tp/documentation/docs.md

Документация 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

Ответ:

{
  "status": "healthy",
  "timestamp": "Tue, 02 Jan 2024 10:00:00 UTC"
}

2. Аутентификация (публичные маршруты)

Регистрация пользователя

POST /v1/auth/register

Тело запроса (ожидается):

{
  "email": "user@example.com",
  "password": "secure_password",
  "name": "Имя пользователя"
}

Авторизация пользователя

POST /v1/auth/login

Тело запроса (ожидается):

{
  "email": "user@example.com",
  "password": "secure_password"
}

3. Пользователи (защищенные маршруты - требуется JWT токен)

Получение всех пользователей

GET /v1/api/users/

Заголовок:

Authorization: Bearer <JWT_TOKEN>

Создание пользователя

POST /v1/api/users/

Заголовок:

Authorization: Bearer <JWT_TOKEN>

Получение пользователя по ID

GET /v1/api/users/{id}

Заголовок:

Authorization: Bearer <JWT_TOKEN>

Модель данных

Пользователь (UserT)

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 пакете)

Запуск

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)

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)

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)

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 кластере.

---

Примечание: Это предварительная документация. Реализация новых эндпоинтов будет сопровождаться обновлением документации.