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 Сетевые сегменты
```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**