READMI Добавил

README.md

@@ -0,0 +1,230 @@
+# ⚽ 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
+
+------------------------------------------------------------------------
+
+# 📬 Контакты
+
+Для доработок и улучшений --- пиши 👍