From 0a8e51a34964572f73c0d48700901c2722f4c203 Mon Sep 17 00:00:00 2001 From: valitovgaziz Date: Tue, 2 Dec 2025 21:00:17 +0500 Subject: [PATCH] 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 --- main_dc/BB/api_bb/documentation/docs.md | 372 ++++++++++++++++++++++++ main_dc/BB/api_bb/readme.md | 2 +- 2 files changed, 373 insertions(+), 1 deletion(-) create mode 100644 main_dc/BB/api_bb/documentation/docs.md diff --git a/main_dc/BB/api_bb/documentation/docs.md b/main_dc/BB/api_bb/documentation/docs.md new file mode 100644 index 0000000..f05e0cd --- /dev/null +++ b/main_dc/BB/api_bb/documentation/docs.md @@ -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 +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 может изменяться.* \ No newline at end of file diff --git a/main_dc/BB/api_bb/readme.md b/main_dc/BB/api_bb/readme.md index 453f054..050c9c9 100644 --- a/main_dc/BB/api_bb/readme.md +++ b/main_dc/BB/api_bb/readme.md @@ -1,4 +1,4 @@ -go-rest-api/ +api_bb/ ├── cmd/ │ └── server/ │ └── main.go