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
This commit is contained in:
@@ -0,0 +1,372 @@
|
|||||||
|
# Документация проекта 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 может изменяться.*
|
||||||
@@ -1,4 +1,4 @@
|
|||||||
go-rest-api/
|
api_bb/
|
||||||
├── cmd/
|
├── cmd/
|
||||||
│ └── server/
|
│ └── server/
|
||||||
│ └── main.go
|
│ └── main.go
|
||||||
|
|||||||
Reference in New Issue
Block a user