# Документация проекта 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 # Точные версии зависимостей ``` ### Архитектурные принципы 1. **Чистая архитектура**: Разделение на слои (handler → service → repository → model) 2. **Domain-Driven Design**: Бизнес-модели в центре архитектуры 3. **Dependency Injection**: Внедрение зависимостей через конструкторы 4. **REST API**: Стандартные RESTful endpoints 5. **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 1. **AuthMiddleware**: проверка JWT токена 2. **RequireAuth**: требование аутентификации 3. **AdminMiddleware**: проверка прав администратора ## Безопасность ### Меры защиты 1. **Хеширование паролей**: bcrypt 2. **SQL инъекции**: защита через GORM 3. **CORS**: настройка политик 4. **Валидация**: входных данных 5. **Лимиты запросов**: предотвращение 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 ``` ### Конфигурационный файл ```go type Config struct { DBHost string DBPort string DBUser string DBPassword string DBName string JWTSecret string Email EmailConfig } ``` ## Развертывание ### Требования 1. Go 1.25+ 2. PostgreSQL 12+ 3. SMTP сервер для email ### Шаги развертывания ```bash # Клонирование репозитория git clone 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 ``` ## Тестирование ### Типы тестов 1. **Юнит-тесты**: тестирование отдельных функций 2. **Интеграционные тесты**: тестирование взаимодействия с БД 3. **E2E тесты**: тестирование API endpoints ### Запуск тестов ```bash # Все тесты 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 # Детальная проверка ``` ### Метрики - Количество запросов - Время ответа - Ошибки по типам - Использование ресурсов ## Масштабирование ### Горизонтальное масштабирование 1. **Stateless архитектура**: легкое добавление инстансов 2. **Балансировка нагрузки**: через nginx или cloud load balancer 3. **Кэширование**: Redis для частых запросов ### Вертикальное масштабирование 1. **Оптимизация запросов**: индексы в БД 2. **Connection pooling**: настройка пулов соединений 3. **Асинхронная обработка**: фоновые задачи ## Дорожная карта развития ### Ближайшие планы 1. **WebSocket**: реальное время для событий 2. **Push-уведомления**: через Firebase Cloud Messaging 3. **Интеграция с Strava**: импорт тренировок 4. **Социальные функции**: друзья, группы, чаты ### Долгосрочные цели 1. **Мобильное приложение**: React Native 2. **Аналитика**: расширенная статистика 3. **Партнерская программа**: интеграция с магазинами 4. **Интернационализация**: поддержка других языков ## Контакты и поддержка ### Команда проекта - **Разработка**: [Ваши контакты] - **Дизайн**: [Ваши контакты] - **Контент**: [Ваши контакты] ### Документация - **API документация**: Swagger/OpenAPI - **Руководство пользователя**: на сайте begushiybashkir.ru - **Разработчикам**: README и примеры кода ### Сообщество - **Telegram канал**: [ссылка] - **Группа VK**: [ссылка] - **Instagram**: [ссылка] --- *Документация обновлена: декабрь 2025 года* *Проект находится в активной разработке. API может изменяться.*