# ⚽ Match Management & vMix Integration System

Полноценная система управления футбольными матчами с live-обновлением,
парсингом данных и интеграцией с vMix.

------------------------------------------------------------------------

# 📌 Описание

Проект состоит из нескольких ключевых частей:

-   FastAPI сервер (админка + API)
-   Scheduler (live-обновления матчей)
-   Парсеры (игры, расписание, таблица)
-   PostgreSQL база данных
-   WebSocket сервер для vMix

------------------------------------------------------------------------

# 🧱 Архитектура системы

                    ┌──────────────┐
                    │   Scheduler  │
                    │              │
                    │ matches_loop │
                    │ standings    │
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
            ▼              ▼              ▼
     live_match_worker  parser_game   parser_standings
            │
            ▼
         Database
            │
            ▼
          FastAPI
            │
            ▼
          vMix

------------------------------------------------------------------------

# 🗄 Структура базы данных

## Таблица: matches

  Поле          Тип         Описание
  ------------- ----------- ----------------------
  id            int         ID матча
  external_id   text        ID матча на сайте
  match_date    timestamp   дата и время
  status        text        статус матча
  home_score    int         счет хозяев
  away_score    int         счет гостей
  updated_at    timestamp   последнее обновление

------------------------------------------------------------------------

## Таблица: standings

  Поле       Тип   Описание
  ---------- ----- ----------
  team_id    int   команда
  position   int   позиция
  points     int   очки
  played     int   сыграно

------------------------------------------------------------------------

## Таблица: match_lineup_players

-   составы команд
-   старт + запас

------------------------------------------------------------------------

## Таблица: match_events

-   события матча (голы, карточки и т.д.)

------------------------------------------------------------------------

# 🔄 Основные процессы

## 1. Scheduler

Работает как отдельный процесс:

### Каждую минуту:

-   ищет матчи на сегодня
-   запускает worker за 1 минуту до начала

### Worker:

-   раз в минуту:
    -   парсит сайт
    -   обновляет счет и статус
-   останавливается при finished

------------------------------------------------------------------------

## 2. Обновление турнирной таблицы

-   вызывается `parser_standings`
-   обновляет standings в БД
-   запускается раз в минуту

------------------------------------------------------------------------

## 3. FastAPI

Обеспечивает:

-   админку
-   API для vMix
-   WebSocket соединения

------------------------------------------------------------------------

# 📡 API Endpoints

## Основные

### Матчи

-   GET /admin/matches
-   GET /admin/session/{session_token}

------------------------------------------------------------------------

### vMix

-   GET /vmix/session/{session_token}/info
-   GET /vmix/session/{session_token}/standings
-   GET /vmix/session/{session_token}/schedule
-   GET /vmix/session/{session_token}/scoreboard

------------------------------------------------------------------------

### WebSocket

    /ws/vmix-client

Функции: - регистрация клиентов - heartbeat - отправка команд

------------------------------------------------------------------------

# ⚙️ Запуск проекта

## 1. Установка

    pip install -r requirements.txt

------------------------------------------------------------------------

## 2. Настройка БД

Отредактировать:

    db.py

------------------------------------------------------------------------

## 3. Запуск

### API

    uvicorn app:app --reload

### Scheduler

    python scheduler.py

------------------------------------------------------------------------

# ❗ ВАЖНО

Scheduler должен запускаться отдельно.

НЕЛЬЗЯ:

    run_scheduler()

внутри FastAPI.

------------------------------------------------------------------------

# 🔧 Что нужно реализовать

## fetch_match_live_data()

    def fetch_match_live_data(match_row):
        return {
            "status": "live",
            "home_score": 1,
            "away_score": 0
        }

------------------------------------------------------------------------

# 🚀 Рекомендации

-   запускать scheduler отдельно
-   использовать 1 worker для API
-   добавить логирование
-   обрабатывать ошибки парсинга

------------------------------------------------------------------------

# 📌 Dev режим

    uvicorn app:app --reload
    python scheduler.py

------------------------------------------------------------------------

# 🧠 Production

-   API отдельно
-   Scheduler отдельно
-   supervisor / systemd

------------------------------------------------------------------------

# 📬 Контакты

Для доработок и улучшений --- пиши 👍