tp/main_dc/BB/documentation/docs.md

📚 Полная документация проекта "Бегущий Башкир"

Версия 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_YAL │   │
│  │ (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 Сетевые сегменты

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 Сервисы кластера

Основные сервисы "Бегущий Башкир":

api_bb:           # REST API на Go (порт 7777)
  - Ядро бизнес-логики
  - Аутентификация и авторизация
  - Управление тренировками и событиями
  - Обработка достижений и статистики

db_bb:            # База данных (порт 5433)
  - Изолированная БД для проекта
  - Хранение всех данных бегового клуба
  - Автоматическое резервное копирование

nginx:            # Веб-сервер (порты 80/443)
  - Статический контент Vue SPA
  - Проксирование к API
  - SSL/TLS терминация
  - Кэширование и сжатие

Общие сервисы кластера:

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 (тома данных)

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:

healthcheck:
  test: ["CMD", "wget", "--spider", "http://localhost:8080/api/health"]

---

🗄️ СТРУКТУРА ДАННЫХ (API_BB)

4.1 Основные сущности

Пользователь (User)

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)

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)

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)

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 Цветовая схема

$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 Основные эндпоинты

Аутентификация

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}

Пользователи

GET    /users/profile
PUT    /users/profile
GET    /users/{id}/achievements
GET    /users/{id}/stats

Тренировки

GET    /workouts?date_from=&date_to=&type=
POST   /workouts
GET    /workouts/{id}
PUT    /workouts/{id}
DELETE /workouts/{id}
GET    /workouts/stats/monthly

События

GET    /events?type=&status=
GET    /events/{id}
POST   /events/{id}/register
DELETE /events/{id}/register
GET    /events/my-registrations

Достижения

GET    /achievements?type=&verified=
POST   /achievements
PUT    /achievements/{id}
GET    /achievements/types

7.4 Пример запроса

// Регистрация пользователя
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 Настройка окружения

# 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 Регулярные задачи

# Ежедневно
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 Резервное копирование

# 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 Восстановление

# Восстановление БД
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 Конфигурация для продакшена

# В 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 не работает

# Решение:
docker-compose logs certbot
docker-compose exec certbot certbot renew --dry-run
# Проверить DNS записи

Проблема: API не отвечает

# Решение:
docker-compose ps api_bb
docker-compose logs api_bb
curl http://localhost:7777/api/health
# Проверить подключение к БД

Проблема: База данных не запускается

# Решение:
docker-compose logs db_bb
docker volume ls
# Проверить права на volume

12.2 Инструменты отладки

# Проверка сети
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 (рекомендации)

# .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 Тестирование

# 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 Политики

• Политика конфиденциальности
• Условия использования
• Политика 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