Files

T

valitovgaziz 0a8e51a349 new file: main_dc/BB/api_bb/documentation/docs.md

modified:   main_dc/BB/api_bb/readme.md
add docs for REST API begushiybashkir.ru

2025-12-02 21:00:17 +05:00

15 KiB

Raw Blame History

Документация проекта API бегущего башкира

Обзор проекта

API бегущего башкира — это REST API сервис для бегового сообщества Башкортостана, разработанный на Go с использованием современных технологий и архитектурных подходов. Проект предоставляет комплексную платформу для управления тренировками, событиями, достижениями и взаимодействия между бегунами.

Текущая версия: v1 (декабрь 2025)

Стек технологий

Основные технологии

Язык: Go 1.25.1
Веб-фреймворк: Chi v5 (роутер)
ORM: GORM v1.31.0 с драйвером PostgreSQL
Аутентификация: JWT (golang-jwt/jwt/v5)
Валидация: validator/v10

Вспомогательные библиотеки

Логирование: Zap
Конфигурация: godotenv
Работа с email: go-mail
Хеширование паролей: bcrypt (golang.org/x/crypto)
CORS: go-chi/cors
UUID: google/uuid

База данных

Основная СУБД: PostgreSQL
Миграции: встроенные через GORM AutoMigrate

Архитектура проекта

Структура каталогов

api_bb/
├── cmd/
│   └── server/
│       └── main.go                 # Точка входа
├── internal/
│   ├── config/
│   │   └── config.go              # Конфигурация приложения
│   ├── handlers/
│   │   ├── handlers.go            # Основной обработчик
│   │   ├── health.go              # Health check endpoints
│   │   ├── auth.go                # Аутентификация
│   │   └── ... другие обработчики
│   ├── models/
│   │   ├── user.go                # Модель пользователя
│   │   ├── workout.go             # Модель тренировки
│   │   ├── event.go               # Модель события
│   │   ├── achievement.go         # Модель достижений
│   │   ├── training_plan.go       # Модель плана тренировок
│   │   ├── news.go                # Модель новостей
│   │   ├── review.go              # Модель отзывов
│   │   ├── gallery.go             # Модель галереи
│   │   ├── personal_best.go       # Модель личных рекордов
│   │   ├── user_stats.go          # Модель статистики пользователя
│   │   ├── email.go               # Модель email верификации
│   │   └── common.go              # Общие DTO и структуры
│   ├── repository/
│   │   └── user_repository.go     # Репозиторий пользователей
│   │   └── ... другие репозитории
│   ├── service/
│   │   └── auth_service.go        # Сервис аутентификации
│   │   └── ... другие сервисы
│   └── routes/
│       └── routes.go              # Настройка маршрутов
├── pkg/
│   ├── database/
│   │   └── database.go            # Подключение к БД
│   └── middleware/
│       └── middleware.go          # Middleware функции
├── go.mod                         # Зависимости
└── go.sum                         # Точные версии зависимостей

Архитектурные принципы

Чистая архитектура: Разделение на слои (handler → service → repository → model)
Domain-Driven Design: Бизнес-модели в центре архитектуры
Dependency Injection: Внедрение зависимостей через конструкторы
REST API: Стандартные RESTful endpoints
JWT аутентификация: Stateless авторизация

Основные сущности

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

Основные поля: ID, email, имя, фамилия, аватар, телефон
Дополнительно: опыт, цели, подписка на рассылку
Роли: user, admin
Аутентификация: email + password, JWT токены

Тренировка (Workout)

Типы: easy, tempo, interval, long, recovery
Метрики: дистанция, продолжительность, темп, калории
Дополнительно: заметки, дата тренировки

Событие (Event)

Типы: race (забег), training (тренировка), social (встреча), workshop (семинар)
Характеристики: дата, место, дистанция, количество участников
Регистрация: открытая/закрытая, с ограничениями

Достижения (Achievement)

Типы: distance (дистанция), speed (скорость), consistency (последовательность), event (событие), special (особые)
Подтверждение: верифицированные/неверифицированные
Бейджи: изображения достижений

Личные рекорды (Personal Best)

Дистанции: 5к, 10к, полумарафон, марафон, другие
Данные: время, темп, дата, место проведения
Подтверждение: верифицированные результаты

Новости (News)

Категории: events, training, achievements, community
Контент: заголовок, краткое описание, полный текст, изображение
Взаимодействие: просмотры, комментарии

Отзывы (Review)

Оценка: 1-5 звезд
Дополнительно: достижения, дистанции, улучшения
Верификация: подтвержденные отзывы

Галерея (Gallery)

Категории: training, events, community, achievements
Контент: фотографии с описанием
Взаимодействие: просмотры, лайки

Тренировочные планы (Training Plan)

Структура: недельные планы с тренировками
Прогресс: текущая неделя, завершенные тренировки
Цели: целевая дата и дистанция

Маршруты API

Группы маршрутов

1. Аутентификация и пользователи

POST   /v1/auth/register           # Регистрация
POST   /v1/auth/login              # Вход
POST   /v1/auth/logout             # Выход
GET    /v1/user/profile            # Профиль пользователя
POST   /v1/user/editProfile        # Обновление профиля

2. Тренировки

POST   /v1/user/workouts           # Создание тренировки
GET    /v1/user/workouts           # Получение тренировок
GET    /v1/user/workouts/stats     # Статистика тренировок
PUT    /v1/user/workouts/{id}      # Обновление тренировки
DELETE /v1/user/workouts/{id}      # Удаление тренировки

3. События

GET    /v1/events                  # Все события
GET    /v1/events/upcoming         # Предстоящие события
POST   /v1/events/register         # Регистрация на событие
GET    /v1/events/my/registrations # Мои регистрации

4. Достижения

POST   /v1/user/achievements       # Создание достижения
GET    /v1/user/achievements       # Мои достижения
GET    /v1/achievements/user/{id}  # Достижения пользователя (публичные)
PUT    /v1/user/achievements/{id}  # Обновление достижения

5. Личные рекорды

POST   /v1/user/personal-bests     # Создание рекорда
GET    /v1/user/personal-bests     # Мои рекорды
GET    /v1/user/personal-bests/summary # Сводка рекордов
PUT    /v1/user/personal-bests/{id} # Обновление рекорда

6. Новости

GET    /v1/news                    # Все новости
GET    /v1/news/{id}               # Конкретная новость
POST   /v1/news                    # Создание новости (админ)
POST   /v1/news/{id}/comments      # Комментарий к новости

7. Отзывы

GET    /v1/reviews                 # Все отзывы
GET    /v1/reviews/stats           # Статистика отзывов
POST   /v1/reviews                 # Создание отзыва
GET    /v1/reviews/my              # Мои отзывы

8. Верификация email и сброс пароля

GET    /v1/verify-email            # Верификация email
POST   /v1/auth/verify-email/resend # Повторная отправка
POST   /v1/auth/password-reset/request # Запрос сброса
POST   /v1/auth/password-reset/confirm # Подтверждение сброса

Аутентификация и авторизация

JWT Токены

Access Token: краткосрочный (15-60 минут)
Refresh Token: долгосрочный (7-30 дней)
Хранение: HTTP-only cookies или заголовок Authorization

Middleware

AuthMiddleware: проверка JWT токена
RequireAuth: требование аутентификации
AdminMiddleware: проверка прав администратора

Безопасность

Меры защиты

Хеширование паролей: bcrypt
SQL инъекции: защита через GORM
CORS: настройка политик
Валидация: входных данных
Лимиты запросов: предотвращение DDoS

Безопасность данных

Чувствительные данные не возвращаются в ответах
Пароли никогда не логируются
Сессии через JWT (stateless)

Конфигурация

Переменные окружения

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=api_bb
JWT_SECRET=your-secret-key
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-password

Конфигурационный файл

type Config struct {
    DBHost     string
    DBPort     string
    DBUser     string
    DBPassword string
    DBName     string
    JWTSecret  string
    Email      EmailConfig
}

Развертывание

Требования

Go 1.25+
PostgreSQL 12+
SMTP сервер для email

Шаги развертывания

# Клонирование репозитория
git clone <repository-url>
cd api_bb

# Установка зависимостей
go mod download

# Настройка переменных окружения
cp .env.example .env
# редактирование .env

# Запуск миграций
go run cmd/server/main.go migrate

# Запуск сервера
go run cmd/server/main.go serve

# Или сборка
go build -o api_bb cmd/server/main.go
./api_bb serve

Тестирование

Типы тестов

Юнит-тесты: тестирование отдельных функций
Интеграционные тесты: тестирование взаимодействия с БД
E2E тесты: тестирование API endpoints

Запуск тестов

# Все тесты
go test ./...

# С покрытием
go test -cover ./...

# Конкретный пакет
go test ./internal/handlers

Мониторинг и логирование

Логирование

Уровни: Debug, Info, Warn, Error
Форматы: JSON (продакшн), Text (разработка)
Контекст: request ID, пользователь, время выполнения

Health checks

GET /api/health    # Общая проверка
GET /api/check     # Детальная проверка

Метрики

Количество запросов
Время ответа
Ошибки по типам
Использование ресурсов

Масштабирование

Горизонтальное масштабирование

Stateless архитектура: легкое добавление инстансов
Балансировка нагрузки: через nginx или cloud load balancer
Кэширование: Redis для частых запросов

Вертикальное масштабирование

Оптимизация запросов: индексы в БД
Connection pooling: настройка пулов соединений
Асинхронная обработка: фоновые задачи

Дорожная карта развития

Ближайшие планы

WebSocket: реальное время для событий
Push-уведомления: через Firebase Cloud Messaging
Интеграция с Strava: импорт тренировок
Социальные функции: друзья, группы, чаты

Долгосрочные цели

Мобильное приложение: React Native
Аналитика: расширенная статистика
Партнерская программа: интеграция с магазинами
Интернационализация: поддержка других языков

Контакты и поддержка

Команда проекта

Разработка: [Ваши контакты]
Дизайн: [Ваши контакты]
Контент: [Ваши контакты]

Документация

API документация: Swagger/OpenAPI
Руководство пользователя: на сайте begushiybashkir.ru
Разработчикам: README и примеры кода

Сообщество

Telegram канал: [ссылка]
Группа VK: [ссылка]
Instagram: [ссылка]

Документация обновлена: декабрь 2025 года Проект находится в активной разработке. API может изменяться.

15 KiB Raw Blame History Unescape Escape