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/
|
||||
│ └── server/
|
||||
│ └── main.go
|
||||
|
||||
Reference in New Issue
Block a user