valitovgaziz/tp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new file: main_dc/BB/README.md

Browse Source 
new file:   main_dc/BB/documentation/docs.md
add general and README.md file for BB project
This commit is contained in:
Газиз Валитов
2025-12-04 07:28:54 +05:00
parent 1776b8c410
commit daac28b869
2 changed files with 957 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
main_dc/BB/documentation/docs.md
+780
View File
@@ -0,0 +1,780 @@
# 📚 Полная документация проекта "Бегущий Башкир"
## Версия 1.0 | Декабрь 2025
---
## 🏃‍♂️ ОПИСАНИЕ ПРОЕКТА
### 1.1 Общая концепция
**"Бегущий Башкир"** — комплексная цифровая платформа для бегового клуба, объединяющая веб-сайт, REST API и аналитические сервисы. Проект создан для развития бегового сообщества Республики Башкортостан и предоставляет современные инструменты для организации тренировок, мероприятий и взаимодействия между участниками.
### 1.2 Основные цели
- Создание централизованной системы управления беговым клубом
- Автоматизация процессов регистрации, учета и статистики
- Формирование активного сообщества бегунов
- Продвижение здорового образа жизни и спорта в регионе
- Сохранение культурных особенностей (поддержка русского и башкирского языков)
### 1.3 Доменные имена
- **Основной сайт:** `begushiybashkir.ru`
- **API сервер:** `api.begushiybashkir.ru` (в перспективе)
- **Дополнительные:** В рамках общего кластера с другими проектами
---
## 🏗️ АРХИТЕКТУРА СИСТЕМЫ
### 2.1 Компонентная диаграмма
```
┌─────────────────────────────────────────────────────────────┐
│ Docker Compose Cluster │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Nginx │ │ API_TP │ │ API_BB │ │ API_ES │ │
│ │ (Proxy) │◄─┤(Yalarba) │ │(Бег.Баш)│ │(Easysite)│ │
│ └────┬─────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ┌────▼─────┐ ┌──────▼────┐ ┌───▼────┐ ┌──────▼────┐ │
│ │ Certbot │ │ DB │ │ DB_BB │ │ DB_TP │ │
│ │ (SSL) │ │ (Postgres)│ │(Postgr)│ │ (Postgres)│ │
│ └──────────┘ └───────────┘ └────────┘ └───────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Analytics │ │ Easysite │ │ Vue SPA │ │ StubSite │ │
│ │ (Node.js)│ │ (Nuxt.js)│ │(Frontend)│ │ (Загл.) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 Сетевые сегменты
```yaml
networks:
web-network: # Внешний доступ (80/443 порты)
internal: # Внутренняя коммуникация
app-network: # Для Yalarba/Easysite приложений
bb-network: # Изолированная сеть "Бегущий Башкир"
```
### 2.3 Технологический стек
#### Backend
- **Go 1.25.1** (API сервисы)
- **Chi Router** v5 (HTTP роутинг)
- **GORM** v1.31.0 (ORM для PostgreSQL)
- **JWT** (аутентификация)
- **Validator** v10 (валидация данных)
#### Frontend
- **Vue 3** (Composition API)
- **Vite** (сборка)
- **Pinia** (управление состоянием)
- **Vue Router** (навигация)
- **SCSS/CSS3** (стили)
#### Базы данных
- **PostgreSQL 15** (основные данные)
- **Альпийский образ** (легковесная версия)
#### Инфраструктура
- **Docker & Docker Compose**
- **Nginx** (обратный прокси)
- **Certbot** (SSL сертификаты)
- **Node.js** (аналитика)
---
## 📦 DOCKER КОМПОЗИЦИЯ
### 3.1 Сервисы кластера
#### Основные сервисы "Бегущий Башкир":
```yaml
api_bb: # REST API на Go (порт 7777)
- Ядро бизнес-логики
- Аутентификация и авторизация
- Управление тренировками и событиями
- Обработка достижений и статистики
db_bb: # База данных (порт 5433)
- Изолированная БД для проекта
- Хранение всех данных бегового клуба
- Автоматическое резервное копирование
nginx: # Веб-сервер (порты 80/443)
- Статический контент Vue SPA
- Проксирование к API
- SSL/TLS терминация
- Кэширование и сжатие
```
#### Общие сервисы кластера:
```yaml
certbot: # SSL сертификаты
- Автоматическое обновление Let's Encrypt
- Поддержка wildcard сертификатов
- Мониторинг истечения срока
analytics: # Аналитика (порт 9999)
- Сбор статистики посещений
- Аналитика пользовательского поведения
- Генерация отчетов
```
### 3.2 Порты и доступ
| Сервис | Порт | Назначение | Доступ |
|--------|------|------------|---------|
| nginx | 80 | HTTP | публичный |
| nginx | 443 | HTTPS | публичный |
| api_bb | 7777 | API | внутренний |
| db_bb | 5433 | База данных | внутренний |
| analytics | 9999 | Аналитика | внутренний |
### 3.3 Volumes (тома данных)
```yaml
db_bb_data: # Основные данные БД
api_bb_uploads: # Загружаемые файлы (фото, документы)
analytics_logs: # Логи аналитики
analytics_data: # Данные аналитики
certbot_data: # SSL сертификаты
certbot_www: # Веб-контент для верификации
```
### 3.4 Health Checks
Все сервисы включают проверки здоровья:
- **Интервал:** 30 секунд
- **Таймаут:** 10 секунд
- **Попытки:** 3-5 раз
- **Период старта:** 40 секунд
Пример для API:
```yaml
healthcheck:
test: ["CMD", "wget", "--spider", "http://localhost:8080/api/health"]
```
---
## 🗄️ СТРУКТУРА ДАННЫХ (API_BB)
### 4.1 Основные сущности
#### Пользователь (User)
```sql
CREATE TABLE users (
id UUID PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
first_name VARCHAR(100),
last_name VARCHAR(100),
avatar_url TEXT,
phone VARCHAR(20),
experience_level INTEGER, -- 1: новичок, 2: любитель, 3: профессионал
goals TEXT[], -- массив целей
newsletter_subscription BOOLEAN DEFAULT true,
role VARCHAR(20) DEFAULT 'user', -- user, admin
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
```
#### Тренировка (Workout)
```sql
CREATE TABLE workouts (
id UUID PRIMARY KEY,
user_id UUID REFERENCES users(id),
type VARCHAR(50), -- easy, tempo, interval, long, recovery
distance_km DECIMAL(5,2),
duration_minutes INTEGER,
avg_pace_min_per_km DECIMAL(4,2),
calories_burned INTEGER,
notes TEXT,
workout_date DATE NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
```
#### Событие (Event)
```sql
CREATE TABLE events (
id UUID PRIMARY KEY,
title VARCHAR(255) NOT NULL,
description TEXT,
type VARCHAR(50), -- race, training, social, workshop
event_date TIMESTAMP NOT NULL,
location VARCHAR(255),
distance_km DECIMAL(5,2),
max_participants INTEGER,
is_registration_open BOOLEAN DEFAULT true,
registration_deadline TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
```
#### Достижение (Achievement)
```sql
CREATE TABLE achievements (
id UUID PRIMARY KEY,
user_id UUID REFERENCES users(id),
title VARCHAR(255) NOT NULL,
description TEXT,
type VARCHAR(50), -- distance, speed, consistency, event, special
verified BOOLEAN DEFAULT false,
badge_url TEXT,
achieved_date DATE NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
```
### 4.2 Связи между таблицами
- **users** ↔ **workouts** (один ко многим)
- **users** ↔ **achievements** (один ко многим)
- **users** ↔ **events** (многие ко многим через registrations)
- **users** ↔ **personal_bests** (один ко многим)
---
## 🔐 СИСТЕМА БЕЗОПАСНОСТИ
### 5.1 Аутентификация
- **JWT токены** (Access + Refresh)
- **HTTP-only cookies** для клиентского хранения
- **Валидация email** через подтверждение
- **Сброс пароля** через email токены
### 5.2 Авторизация
- **Ролевая модель:** user, admin
- **Middleware защита** маршрутов
- **Проверка прав доступа** к ресурсам
### 5.3 Защита данных
- **BCrypt** для хеширования паролей
- **Подготовленные SQL-запросы** (GORM)
- **Валидация входных данных**
- **CORS политики**
- **Rate limiting** (в разработке)
---
## 🌐 ФРОНТЕНД АРХИТЕКТУРА (Vue SPA)
### 6.1 Структура компонентов
```
src/
├── components/ # Переиспользуемые компоненты
│ ├── NavigationMenu.vue
│ ├── EventCard.vue
│ ├── RegistrationCard.vue
│ ├── StatsChart.vue
│ └── AchievementBadge.vue
├── pages/ # Страницы приложения
│ ├── Home.vue # Главная страница
│ ├── About.vue # О клубе
│ ├── Gallery.vue # Галерея
│ ├── Achievements.vue # Достижения
│ ├── DetailedStats.vue # Статистика
│ ├── Events.vue # События
│ └── Profile.vue # Профиль пользователя
├── stores/ # Состояние (Pinia)
│ ├── auth.js # Авторизация
│ ├── stats.js # Статистика
│ └── events.js # События
├── router/ # Маршрутизация
│ └── index.js
└── assets/ # Ресурсы
├── logo/
├── images/
└── main.scss
```
### 6.2 Цветовая схема
```scss
$primary-color: #2e8b57; // Зеленый (природа, здоровье)
$accent-color: #ffd700; // Золотой (достижения)
$background: #f8fff8; // Светло-зеленый фон
$text-color: #2c3e50; // Темно-серый текст
$error-color: #e74c3c; // Красный для ошибок
$success-color: #27ae60; // Зеленый для успеха
```
### 6.3 Адаптивный дизайн
| Breakpoint | Устройство | Контейнер |
|------------|------------|-----------|
| < 360px | Маленькие телефоны | 100% |
| 360-480px | Телефоны | 100% |
| 481-768px | Планшеты | 720px |
| 769-1024px | Ноутбуки | 960px |
| > 1024px | Десктопы | 1140px |
---
## 🔄 API ДОКУМЕНТАЦИЯ
### 7.1 Базовый URL
```
https://begushiybashkir.ru/api/v1/
```
### 7.2 Статус коды
- `200` - Успех
- `201` - Создано
- `400` - Ошибка валидации
- `401` - Не авторизован
- `403` - Доступ запрещен
- `404` - Не найдено
- `500` - Серверная ошибка
### 7.3 Основные эндпоинты
#### Аутентификация
```http
POST /auth/register
POST /auth/login
POST /auth/logout
POST /auth/refresh-token
POST /auth/password-reset/request
POST /auth/password-reset/confirm
GET /auth/verify-email?token={token}
```
#### Пользователи
```http
GET /users/profile
PUT /users/profile
GET /users/{id}/achievements
GET /users/{id}/stats
```
#### Тренировки
```http
GET /workouts?date_from=&date_to=&type=
POST /workouts
GET /workouts/{id}
PUT /workouts/{id}
DELETE /workouts/{id}
GET /workouts/stats/monthly
```
#### События
```http
GET /events?type=&status=
GET /events/{id}
POST /events/{id}/register
DELETE /events/{id}/register
GET /events/my-registrations
```
#### Достижения
```http
GET /achievements?type=&verified=
POST /achievements
PUT /achievements/{id}
GET /achievements/types
```
### 7.4 Пример запроса
```javascript
// Регистрация пользователя
fetch('/api/v1/auth/register', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'user@example.com',
password: 'SecurePass123!',
firstName: 'Иван',
lastName: 'Иванов',
phone: '+79161234567'
})
});
```
---
## 🚀 РАЗВЕРТЫВАНИЕ
### 8.1 Требования
- Docker 20.10+
- Docker Compose 2.0+
- 2 ГБ RAM минимум
- 10 ГБ свободного места
- Доступ к портам 80, 443
### 8.2 Настройка окружения
```bash
# 1. Клонирование
git clone <repository>
cd project
# 2. Настройка переменных
cp .env.example .env
# Редактируем .env:
# EMAIL=admin@example.com
# ALL_DOMAINS=begushiybashkir.ru,www.begushiybashkir.ru
# DB_PASSWORD=strong_password
# 3. Запуск
docker-compose up -d
# 4. Проверка
docker-compose ps
docker-compose logs -f nginx
```
### 8.3 Настройка DNS
```
A запись: begushiybashkir.ru → IP сервера
CNAME запись: www → begushiybashkir.ru
```
### 8.4 Первоначальная настройка
1. **Проверка SSL:** `https://begushiybashkir.ru`
2. **Проверка API:** `https://begushiybashkir.ru/api/health`
3. **Создание админа:** через миграции или CLI
4. **Настройка SMTP:** для email рассылок
---
## 📊 МОНИТОРИНГ И ЛОГИРОВАНИЕ
### 9.1 Логи
- **Nginx:** доступы и ошибки
- **API:** бизнес-логика и ошибки
- **База данных:** медленные запросы
- **Docker:** системные логи
### 9.2 Health Checks
```
GET /health # Общий статус
GET /api/health # Статус API
GET /database/health # Статус БД
```
### 9.3 Метрики
- **Количество пользователей**
- **Активные тренировки**
- **Регистрации на события**
- **Время отклика API**
- **Ошибки по типам**
---
## 🔧 ОБСЛУЖИВАНИЕ
### 10.1 Регулярные задачи
```bash
# Ежедневно
docker-compose exec db_bb pg_dump -U postgres bb_db > backup.sql
# Еженедельно
docker-compose restart nginx
docker system prune -a
# Ежемесячно
certbot renew --dry-run
check disk usage
```
### 10.2 Резервное копирование
```yaml
# docker-compose.backup.yml
version: '3.8'
services:
backup:
image: postgres:15-alpine
volumes:
- ./backups:/backups
command: >
sh -c "
PGPASSWORD=postgres pg_dump -h db_bb -U postgres bb_db >
/backups/bb_db_$(date +%Y%m%d_%H%M%S).sql
"
```
### 10.3 Восстановление
```bash
# Восстановление БД
docker-compose exec -T db_bb psql -U postgres bb_db < backup.sql
# Восстановление загруженных файлов
cp -r backup/uploads/* ./api_bb_uploads/
```
---
## 📈 МАСШТАБИРОВАНИЕ
### 11.1 Горизонтальное
1. Добавление инстансов API
2. Балансировка через Nginx
3. Кэширование через Redis
4. Репликация БД
### 11.2 Вертикальное
1. Увеличение ресурсов контейнеров
2. Оптимизация индексов БД
3. Кэширование частых запросов
4. Асинхронная обработка задач
### 11.3 Конфигурация для продакшена
```yaml
# В docker-compose.prod.yml
services:
api_bb:
deploy:
replicas: 3
resources:
limits:
memory: 512M
reservations:
memory: 256M
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
```
---
## 🐛 ОТЛАДКА И УСТРАНЕНИЕ НЕИСПРАВНОСТЕЙ
### 12.1 Частые проблемы
#### Проблема: SSL не работает
```bash
# Решение:
docker-compose logs certbot
docker-compose exec certbot certbot renew --dry-run
# Проверить DNS записи
```
#### Проблема: API не отвечает
```bash
# Решение:
docker-compose ps api_bb
docker-compose logs api_bb
curl http://localhost:7777/api/health
# Проверить подключение к БД
```
#### Проблема: База данных не запускается
```bash
# Решение:
docker-compose logs db_bb
docker volume ls
# Проверить права на volume
```
### 12.2 Инструменты отладки
```bash
# Проверка сети
docker network inspect bb-network
# Проверка томов
docker volume inspect db_bb_data
# Мониторинг ресурсов
docker stats
# Логи в реальном времени
docker-compose logs -f --tail=100
```
---
## 🔄 ЖИЗНЕННЫЙ ЦИКЛ РАЗРАБОТКИ
### 13.1 Git workflow
```
main - продакшн
├── develop - стабильная разработка
│ ├── feature/* - новые функции
│ └── fix/* - исправления
└── release/* - подготовка релизов
```
### 13.2 CI/CD (рекомендации)
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Deploy via SSH
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
script: |
cd /opt/begushiybashkir
git pull
docker-compose down
docker-compose build
docker-compose up -d
```
### 13.3 Тестирование
```bash
# Unit тесты Go
cd api_bb
go test ./...
# E2E тесты API
npm run test:api
# Тесты Vue компонентов
npm run test:unit
# Load testing
k6 run load-test.js
```
---
## 📋 ЧЕКЛИСТ ЗАПУСКА
### 14.1 Предзапусковая проверка
- [ ] Доменное имя настроено и разрешается
- [ ] SSL сертификаты получены
- [ ] Переменные окружения установлены
- [ ] Порты 80 и 443 открыты
- [ ] SMTP настроен для email
- [ ] Резервное копирование настроено
### 14.2 Постзапусковая проверка
- [ ] Сайт доступен по HTTPS
- [ ] API отвечает на health checks
- [ ] Базы данных запущены
- [ ] Статика загружается
- [ ] Email отправляется
- [ ] Мониторинг работает
### 14.3 Проверка безопасности
- [ ] Пароли изменены с дефолтных
- [ ] SSH доступ ограничен
- [ ] Firewall настроен
- [ ] Логирование включено
- [ ] Резервные копии тестируются
---
## 🎯 РАЗВИТИЕ ПРОЕКТА
### 15.1 Ближайшие задачи
1. **Мобильное приложение** (React Native)
2. **Интеграция со Strava**
3. **Платежная система** для мероприятий
4. **Push-уведомления**
5. **Расширенная аналитика**
### 15.2 Долгосрочные цели
1. **Международная поддержка**
2. **Партнерская программа**
3. **Онлайн-марафоны**
4. **AI-тренер**
5. **Социальная сеть бегунов**
### 15.3 Сообщество
- **Telegram канал** для анонсов
- **Группа VK** для обсуждений
- **Instagram** для мотивации
- **YouTube** для обучающего контента
- **Офлайн-встречи** раз в месяц
---
## 📞 ПОДДЕРЖКА И КОНТАКТЫ
### 16.1 Техническая поддержка
- **Экстренные вопросы:** Telegram @tech_support
- **Багрепорты:** GitHub Issues
- **Предложения:** feedback@begushiybashkir.ru
- **Документация:** docs.begushiybashkir.ru (в разработке)
### 16.2 Команда проекта
| Роль | Контакты | Ответственность |
|------|----------|-----------------|
| Тренер | +7 (927) 30-93-095 | Тренировки, мероприятия |
| Разработчик | github.com/dev | Техническая часть |
| Контент-менеджер | @content | Новости, галерея |
| Администратор | admin@ | Управление пользователями |
### 16.3 Время работы поддержки
- **Техподдержка:** 24/7 (автоматически)
- **Консультации:** 10:00-18:00 (МСК)
- **Экстренные случаи:** круглосуточно по телефону
---
## 📄 ЛИЦЕНЗИИ И ПРАВА
### 17.1 Используемое ПО
- **Go:** BSD-3-Clause
- **Vue.js:** MIT
- **PostgreSQL:** PostgreSQL License
- **Docker:** Apache 2.0
### 17.2 Политики
- [Политика конфиденциальности](https://begushiybashkir.ru/privacy)
- [Условия использования](https://begushiybashkir.ru/terms)
- [Политика cookies](https://begushiybashkir.ru/cookies)
---
## 🏆 ОСОБЕННОСТИ ПРОЕКТА
### 18.1 Культурный аспект
- Поддержка башкирского языка
- Учет региональных особенностей
- Пропаганда местного спорта
- Сотрудничество с местными организациями
### 18.2 Технические инновации
- Микросервисная архитектура
- Полная контейнеризация
- Автоматическое SSL
- Резидентная инфраструктура
### 18.3 Социальная значимость
- Бесплатные тренировки для новичков
- Поддержка инклюзивности
- Экологический подход (тренировки на природе)
- Сообщество взаимопомощи
---
## 📝 ИЗМЕНЕНИЯ И ОБНОВЛЕНИЯ
### 19.1 Журнал изменений
```
2025-12-04 v1.0 - Первый релиз
- Базовая функциональность
- API для тренировок и событий
- Vue.js фронтенд
- Docker инфраструктура
```
### 19.2 Процесс обновлений
1. Тестирование на staging окружении
2. Резервное копирование продакшена
3. Поэтапное обновление сервисов
4. Мониторинг после обновления
5. Откат при необходимости
---
**✨ Проект "Бегущий Башкир" — это больше чем веб-сайт. Это цифровое сердце бегового сообщества, соединяющее технологические инновации с духом спорта и дружбы.**
---
*Документация обновлена: 4 декабря 2025 года*
*Проект находится в активной разработке*
*Версия документации: 1.0*
Для актуальной информации посетите:
🌐 **https://begushiybashkir.ru**
📧 **zog1r@mail.ru**
📱 **Telegram: @begushiybashkir**