valitovgaziz
0a8e51a349
modified: main_dc/BB/api_bb/readme.md add docs for REST API begushiybashkir.ru
372 lines
15 KiB
Markdown
372 lines
15 KiB
Markdown
# Документация проекта 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 <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
|
||
```
|
||
|
||
## Тестирование
|
||
|
||
### Типы тестов
|
||
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 может изменяться.* |