# Документация проекта 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 может изменяться.*