From 7d6c97ffc4cc28ee04726315902877a07a17acfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=AE=D1=80=D0=B8=D0=B9=20=D0=A7=D0=B5=D1=80=D0=BD=D0=B5?= =?UTF-8?q?=D0=BD=D0=BA=D0=BE?= Date: Thu, 23 Apr 2026 18:11:30 +0300 Subject: [PATCH] =?UTF-8?q?READMI=20=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D0=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 230 +++++++++++++++++++++++++++++++++++++++++++++++++ README_AUTH.md | 45 ---------- 2 files changed, 230 insertions(+), 45 deletions(-) create mode 100644 README.md delete mode 100644 README_AUTH.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e9dda52 --- /dev/null +++ b/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 + +------------------------------------------------------------------------ + +# 📬 Контакты + +Для доработок и улучшений --- пиши 👍 diff --git a/README_AUTH.md b/README_AUTH.md deleted file mode 100644 index a8b52c6..0000000 --- a/README_AUTH.md +++ /dev/null @@ -1,45 +0,0 @@ -# WFL auth + idle session timeout - -Этот набор добавляет: -- страницу `/login` -- `HttpOnly` cookie `auth_token` -- серверную проверку всех `/admin/*` -- автоматический logout после 2 часов бездействия -- rolling session timeout -- logout кнопку -- обработку `401` для AJAX/fetch - -## Что заменить в проекте - -Скопируй файлы в свой проект: -- `app.py` -> заменить текущий -- `repositories/auth_repository.py` -> новый файл -- `services/auth_service.py` -> новый файл -- `templates/login.html` -> новый файл -- `templates/matches.html` -> заменить -- `templates/match_workspace.html` -> заменить - -## SQL - -Выполни файл: -- `sql/001_auth.sql` - -## Первый админ - -1. Запусти: - `python scripts/create_admin.py` -2. Скопируй выведенный SQL -3. Выполни его в PostgreSQL - -## Важно - -В `app.py` cookie сейчас создаётся так: -- `secure=False` - -Для production под HTTPS поменяй на: -- `secure=True` - -## Что не трогалось - -Твои `match_sessions` оставлены как рабочие сессии матча. -Пользовательская авторизация вынесена отдельно в `admin_users` и `auth_sessions`.