WFL/README.md

⚽ 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

---

📬 Контакты

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