Files

T

valitovgaziz daac28b869 new file: main_dc/BB/README.md

new file:   main_dc/BB/documentation/docs.md
add general and README.md file for BB project

2025-12-04 07:28:54 +05:00

26 KiB

Raw Blame History

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

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

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 Первоначальная настройка

Проверка SSL: https://begushiybashkir.ru
Проверка API: https://begushiybashkir.ru/api/health
Создание админа: через миграции или CLI
Настройка 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 Горизонтальное

Добавление инстансов API
Балансировка через Nginx
Кэширование через Redis
Репликация БД

11.2 Вертикальное

Увеличение ресурсов контейнеров
Оптимизация индексов БД
Кэширование частых запросов
Асинхронная обработка задач

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 Ближайшие задачи

Мобильное приложение (React Native)
Интеграция со Strava
Платежная система для мероприятий
Push-уведомления
Расширенная аналитика

15.2 Долгосрочные цели

Международная поддержка
Партнерская программа
Онлайн-марафоны
AI-тренер
Социальная сеть бегунов

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

🏆 ОСОБЕННОСТИ ПРОЕКТА

18.1 Культурный аспект

Поддержка башкирского языка
Учет региональных особенностей
Пропаганда местного спорта
Сотрудничество с местными организациями

18.2 Технические инновации

Микросервисная архитектура
Полная контейнеризация
Автоматическое SSL
Резидентная инфраструктура

18.3 Социальная значимость

Бесплатные тренировки для новичков
Поддержка инклюзивности
Экологический подход (тренировки на природе)
Сообщество взаимопомощи

📝 ИЗМЕНЕНИЯ И ОБНОВЛЕНИЯ

19.1 Журнал изменений

2025-12-04 v1.0 - Первый релиз
- Базовая функциональность
- API для тренировок и событий
- Vue.js фронтенд
- Docker инфраструктура

19.2 Процесс обновлений

Тестирование на staging окружении
Резервное копирование продакшена
Поэтапное обновление сервисов
Мониторинг после обновления
Откат при необходимости

✨ Проект "Бегущий Башкир" — это больше чем веб-сайт. Это цифровое сердце бегового сообщества, соединяющее технологические инновации с духом спорта и дружбы.

Документация обновлена: 4 декабря 2025 года
Проект находится в активной разработке
Версия документации: 1.0

Для актуальной информации посетите:
🌐 https://begushiybashkir.ru
📧 zog1r@mail.ru
📱 Telegram: @begushiybashkir

26 KiB Raw Blame History Unescape Escape