hockey_new/README.md

Hockey Stat2TV / UI Builder — BUILD 2026.07.20.13

Базы данных

Проект использует две удалённые PostgreSQL-базы:

WFL_DATABASE_URL    → только чтение аккаунтов WFL для авторизации
HOCKEY_DATABASE_URL → все хоккейные данные и рабочие сессии

Локальная SQLite отключена. Файл data/hockey.sqlite3 не создаётся и не используется. Если HOCKEY_DATABASE_URL отсутствует, указывает не на PostgreSQL или сервер недоступен, приложение прекращает запуск.

Настройка

1. Создайте отдельную PostgreSQL-базу hockey рядом с WFL либо используйте уже подготовленную удалённую базу.
2. Скопируйте .env.example в .env.
3. Укажите реальные строки подключения:

HOCKEY_AUTH_MODE=wfl
WFL_DATABASE_URL=postgresql+psycopg://postgres:password@localhost:5432/wfl_db
HOCKEY_DATABASE_URL=postgresql+psycopg://postgres:password@localhost:5432/hockey
HOCKEY_COOKIE_SECURE=false

Подробная настройка прав: REMOTE_DATABASE.md.

Запуск

START.bat

Перед запуском интерфейса скрипт проверяет удалённую базу. При успешном соединении выводится:

[Hockey DB] PostgreSQL connection OK: server:5432/hockey

Проверка из браузера после запуска:

http://127.0.0.1:8000/api/hockey/database/status

Ответ содержит безопасные сведения о подключении без логина и пароля:

{
  "ok": true,
  "backend": "postgresql",
  "host": "server",
  "port": 5432,
  "database": "hockey",
  "remote_only": true
}

Что хранится в удалённой hockey-базе

• турниры, расписание и матчи;
• счёт, периоды, ОТ/Б и арены;
• команды, игроки, тренеры, судьи и страны;
• составы и назначения судей;
• события и удаления;
• сезонная и турнирная статистика;
• powerplay, rank, shots и доступность необязательных ресурсов;
• операторские и веб-сессии;
• кэш полученных XML/JSON и история синхронизации.

Stat2TV остаётся внешним источником XML/JSON, а не базой приложения.

Автоматическая схема

При первом запуске на пустой базе приложение создаёт таблицы автоматически. При обновлении сборки оно добавляет отсутствующие неключевые поля. Пользователю hockey_app необходимы права CREATE, ALTER, SELECT, INSERT, UPDATE, DELETE и права на sequences в схеме базы.

Интерфейс

Сборка включает загрузку матчей Stat2TV, отдельную информационную вкладку «Расписание», события, play-by-play, карты бросков, матчевую и сезонную статистику, турнирные таблицы, большинство, рейтинг, справочники игроков/тренеров/судей/стран, операторские события и vMix JSON.

Расписание команд

Вкладка «Расписание» содержит два режима:

• «Матчи дня» — информационные карточки всех матчей выбранной лиги на текущую дату;
• «Матчи команд» — полный календарь команд текущего открытого матча: левая команда слева, правая справа.

В командном режиме доступны фильтры по статусу, месту проведения и сортировке. Очные матчи выбранных команд выделяются золотой рамкой и подписью «Очная встреча». Карточки остаются информационными и не открывают другой матч.

Управление периодом и буллитами

В шапке выбранного матча доступен ручной выбор текущего периода. Состояние сохраняется в хоккейной PostgreSQL-базе.

Для турниров со стадией regular после вкладки «Игра» появляется вкладка «Буллиты». В ней можно выбрать основную серию на 3 или 5 попыток, назначать игроков обеих команд, отмечать гол/промах и при равном счёте добавлять дополнительные серии по одной попытке каждой команде.

BUILD 2026.07.20.7

• Выпадающий список текущего периода больше не закрывается при обновлении таймера и фоновой синхронизации.
• В регулярном чемпионате доступны три периода, один овертайм, буллиты и завершение матча.
• В плей-офф буллиты скрыты и запрещены на сервере.
• Для плей-офф поддерживается неограниченная последовательность овертаймов: после выбора текущего овертайма автоматически появляется следующий.
• Старое значение ot в плей-офф автоматически преобразуется в ot1.

BUILD 2026.07.20.7

Во вкладке «Буллиты» добавлен независимый быстрый поиск для левой и правой команды. Поиск фильтрует состав по номеру, фамилии и имени.

BUILD 2026.07.20.8 — таймер и численные составы

В общих настройках Stat2TV добавлен раздел «Таймер матча»:

• длительность обычного периода;
• длительность овертайма регулярного чемпионата;
• длительность каждого овертайма плей-офф;
• автоматический сброс основного таймера при смене периода.

При смене периода сбрасывается только основной таймер. Активные удаления и журнал удалений сохраняются. Для нового матча используется длительность обычного периода.

Добавлен раздел «Удаления и численные составы»:

• базовый состав для основного времени, овертайма регулярки и овертайма плей-офф;
• минимальное количество полевых игроков;
• отдельный режим подписи для каждой фазы: PP, только состав (5×4, 4×3) или PP + состав;
• настраиваемые подписи большинства и меньшинства;
• опциональное отображение PK.

По умолчанию основное время отображает PP, овертайм регулярки — фактический состав 4×3, овертайм плей-офф — PP. Текущее численное соотношение и подписи также доступны в scoreboard.json и penalties.json.

BUILD 2026.07.20.9 — видимые настройки таймеров

В административном окне «Настройки» появилась отдельная вкладка «Таймеры и составы». В ней можно менять длительность обычного периода, овертайма регулярного чемпионата и каждого овертайма плей-офф, автоматический сброс времени при смене периода, базовые численные составы и правила подписей PP/PK. Значения сохраняются через общий /api/hockey/settings и применяются без перезапуска.

BUILD 2026.07.20.10 — двуязычная матрица численных составов

В разделе Шестерёнка → Таймеры и составы добавлены отдельные RU/EN-подписи для каждого численного состояния основного времени, овертайма регулярного чемпионата и овертайма плей-офф.

Овертайм регулярки теперь учитывает совпадающие удаления без взаимного погашения: одно удаление — 4×3, два удаления одной команды — 5×3, по одному у каждой команды — 4×4, по два — 5×5.

BUILD 2026.07.20.11 — мгновенное отображение численного состава

• Подготовленное удаление учитывается в численном составе сразу после выбора игрока/команды, нарушения и длительности.
• Запуск таймера удаления больше не требуется для появления 5×4, 4×4, 5×3, 4×3 и настроенной RU/EN-подписи в верхнем счёте.
• Незавершённые заготовки без команды, нарушения или длительности в расчёт не попадают.
• Ответ сохранения таймеров немедленно передаётся в шапку матча без ожидания фонового опроса.

BUILD 2026.07.20.12 — конструктор vMix JSON

Из проекта Golf перенесён переносимый модуль настроек vMix и адаптирован к хоккейным данным.

Откройте Шестерёнка → vMix JSON. В разделе доступны:

• отдельные JSON-пресеты для верхнего счёта, информации о матче, составов, судей, удалений, событий и полного матча;
• включение и перестановка колонок, изменение имени выходного поля и источника данных;
• вычисляемые колонки и формулы из библиотеки vMix;
• дополнительные объединяемые источники (joins);
• просмотр доступных полей выбранного хоккейного источника;
• предварительный просмотр результата для постоянного персонального канала vMix;
• импорт настроек из JSON или ZIP и экспорт текущих пресетов.

Адрес пользовательского JSON формируется для постоянного канала аккаунта и языка:

/vmix/hockey/channel/{channel}/{language}/custom/{key}.json

Поддерживаемые источники: info, scoreboard, home_lineup, away_lineup, officials, penalties, events, full_match.

Чтобы получить рабочую ссылку и список полей, сначала откройте матч. Канал создаётся один раз для WFL-аккаунта и затем сохраняет тот же ключ при входе с другого браузера, перезагрузке страницы и выборе нового матча. Настройки vMix хранятся в settings/vmix_json.json отдельно от подключения Stat2TV. При импорте гольф-проектов старые endpoint-адреса автоматически заменяются хоккейными, а неподдерживаемые источники переводятся на scoreboard без удаления колонок.

BUILD 2026.07.20.13 — постоянные персональные каналы vMix

• Ссылки vMix больше не зависят от временной операторской сессии.
• Для каждого WFL-аккаунта создаётся один постоянный случайный ключ канала.
• При выборе нового матча обновляется привязка канала, но URL в проекте vMix не меняется.
• Пользователь может переключать только канал своего аккаунта; чужой канал нельзя изменить через API.
• Логин не публикуется в URL и не используется как секрет.
• Для отдельных студий рекомендуется создать отдельные WFL-аккаунты: один аккаунт = один постоянный канал.
• Старые адреса /vmix/hockey/session/... оставлены как совместимые алиасы, чтобы существующие проекты не перестали читать данные.

Новый рекомендуемый формат:

/vmix/hockey/channel/{channel}/{language}/custom/{key}.json

vMix Agent Bridge (build 2026.08.11.4)

Новая схема подключения не требует логина внутри agent и не скачивает .vmix проект. Готовый Windows x64 agent находится в agent/agent.exe.

• agent регистрирует постоянный Device ID через /ws/hockey-agent;
• вошедший WFL-пользователь видит устройства в панели vMix Agent и прикрепляет своё;
• на аккаунт можно сохранить несколько устройств, но только одно является активным эфирным;
• при выборе следующего матча активный agent получает новый assignment_id + match_id без перезапуска vMix;
• после reconnect pairing и текущий матч восстанавливаются с сервера;
• команды vMix защищены проверкой текущих assignment_id и match_id;
• build 2026.08.11.4 добавляет первый реальный канал команд: тестовый SetText из web с ожиданием command.ack от agent и ответа локального vMix.

Подробности запуска: agent/README.md.

Mapping Editor / Agent 1.3.0 — build 2026.08.12.1

• Agent 1.3.0 автоматически инвентаризирует текущий vMix: Inputs, key/number/type и GT-поля.
• Сервер сохраняет fingerprint и последнюю структуру проекта в PostgreSQL.
• Admin получил раздел Настройки → Mapping: создание профиля из активного Agent, редактирование связей, обновление структуры и удаление профиля.
• Оператор не может менять mapping; в панели vMix Agent он только видит активный профиль и его версию.
• Mapping привязан к fingerprint графического проекта, а не к матчу или устройству.
• При изменении mapping сервер немедленно отправляет mapping.assigned всем Agent с той же структурой vMix.

Tournament drawer / schedule fallback — build 2026.08.12.2

• Исправлена grid-разметка вкладки «Все турниры»: summary больше не сжимается длинным списком, список скроллится только внутри drawer.
• Автоматический fallback расписания теперь после tournament-scoped файлов проверяет полный набор Stat2TV endpoint-форм, включая варианты с tournament и date query-параметрами.
• Источник online.khl.ru намеренно не скрапится: официальный сайт блокирует автоматические запросы и запрещает автоматизированное извлечение без разрешения.

Build 2026.08.17.1 — Visual Mapping Editor

Mapping теперь настраивается визуально: admin выбирает vMix Input, затем конкретное GT-поле и связывает его с человеческим источником данных текущего матча. В редакторе одновременно показываются понятное название источника, его живое значение и технический data_key. Для связанного текстового/графического поля доступен безопасный тест через выбранный online Agent.

Build 2026.08.17.2 — Context Variables + SQL Data Sources

Mapping Editor больше не зависит от захардкоженного списка data_key. В PostgreSQL добавлены:

• hockey_mapping_context_variables — определения системных и пользовательских идентификаторов;
• hockey_mapping_context_values — значения с изоляцией по account/session/match;
• hockey_mapping_sql_sources — admin-managed read-only SQL SELECT источники.

В Настройки → Mapping доступны вкладки Связи vMix, Переменные, SQL источники. Колонки SQL автоматически становятся ключами source.column, а текущие значения выбранного матча сразу видны в Visual Mapping Editor. SQL выполняется в read-only транзакции с коротким statement timeout на PostgreSQL.

Build 2026.08.17.3

Разделы Переменные и SQL источники вынесены прямо в верхнее меню Настроек рядом с Mapping. Загрузка Mapping API стала отказоустойчивой: ошибка одного endpoint не скрывает остальные разделы.

Build 2026.08.17.5

• SQL Data Source с несколькими строками теперь доступен в Mapping как полноценная таблица.
• Можно выбрать конкретную строку и конкретный столбец без изменения SQL-запроса.
• Ячейки получают внутренний адрес source.row.N.column; старый source.column сохранён и означает первую строку.
• Каталог Mapping читает до 250 строк каждого включённого SQL-источника в read-only режиме.
• В табличном picker есть поиск строки по любому значению.
• vMix Inputs сортируются по номеру Input, затем по названию.
• Добавлен быстрый поиск Input по номеру, названию, key и типу.

Build 2026.08.17.6

• Mapping: для SQL-источника добавлен явный селектор Источник → строка → столбец с живым значением выбранной ячейки.
• Выбранную SQL-ячейку можно напрямую связать с текущим Text/Source полем vMix; технический ключ формируется автоматически.
• Кнопка Тест переименована в Тест поля, чтобы было понятно, что она отправляет только одну связь.
• Добавлена кнопка Применить Input, отправляющая все настроенные поля текущего Input, включая SQL-ячейки, одним batch-запросом.
• Кнопка общего применения переименована в Применить весь Mapping.

Build 2026.08.17.7

• Исправлен SQL Preview в Mapping: кнопка «Проверить SQL» больше не заменяет несохранённый запрос дефолтным SELECT.
• Черновик формы SQL (код, название, категория, описание, SQL, enabled, sort order) сохраняется при Preview и при ошибке выполнения.

Build 2026.08.17.11 — game date fallback from match details

• Если расписание выбранного матча не содержит дату, game_date заполняется из детальной карточки Stat2TV/KHL.
• Поддерживается локализованный формат вида 16 августа 2026, Вс 13:00:00; в PostgreSQL он сохраняется как настоящий DATE (2026-08-16).
• Время 13:00 также извлекается из этой же строки, если отдельное поле времени отсутствует.
• Пустой date/time из последующего refresh расписания больше не стирает значение, уже восстановленное из карточки матча.
• Если в расписании дата есть, она остаётся приоритетной и detail fallback её не перезаписывает.

Build 2026.08.17.12 — game_date recovery

• Localized KHL/Stat2TV dates such as 16 августа 2026, Вс are normalized and stored in hockey_games.game_date as a real DATE (2026-08-16).
• Schedule upsert now recovers date/time from start_datetime_raw if parsed date/time are missing.
• Detail-card save performs a final recovery from the persisted raw datetime before commit.
• Startup backfill repairs existing rows where game_date IS NULL but start_datetime_raw contains a usable date.
• Unicode NBSP/thin spaces are normalized before date parsing.

Build 2026.08.17.13 — SQL Auto Refresh → vMix

• SQL Data Source can now enable Автообновление в vMix and configure a refresh interval from 1 to 3600 seconds.
• Auto refresh runs server-side, so the Mapping admin page does not need to stay open.
• Only Mapping fields linked to the due SQL source are evaluated/sent.
• vMix commands are deduplicated: unchanged values are not sent again.
• Recommended: clocks = 1 s; live statistics = 2–5 s; standings/non-live data = 10–60 s or manual.
• PostgreSQL time formats such as TO_CHAR(NOW(), 'HH24:MI:SS') no longer produce false context parameters (:MI, :SS). PostgreSQL casts such as value::text are also ignored by the context-parameter parser.
• SQL help now includes current-time and timezone examples.

Build 2026.08.17.14

• SQL Source preview no longer hides rows after the first 8.
• Preview renders all rows returned by the server (up to 250) inside a scrollable table with a sticky header.

Build 2026.08.17.15 — series Mapping

• SQL table picker in Mapping now has a real 230–430 px result grid and scroll; rows are no longer visually squeezed below the controls.
• Linked SQL table cells expose Автосвязать столбец: one seed such as Name1.Text ← roster.row.1.fio expands to sequential GT fields and SQL rows.
• Added Размножить строку: configure all columns of one roster row once (for example number + fio), then clone that row pattern across the remaining SQL rows.
• Sequence detection is generic: it detects the strongest numeric token in GT field names rather than requiring a hard-coded PlayerN naming convention.
• A confirmation preview shows generated links before they are written into the unsaved Mapping profile.

Build 2026.08.17.16 — Mapping field filters + fast vMix batch

• vMix Input fields in Mapping are split into three selectors: Text (.Text), Image (.Source) and Color (.Color).
• Added Скрывать связанные toggle for large GT titles.
• Mapping field kind now preserves color as a separate UI type while runtime uses the existing vMix text-value command path.
• New Agent 1.4.0 supports vmix.batch: the server sends the whole resolved Mapping in one WebSocket frame and receives one batch ACK.
• Agent executes independent local vMix HTTP commands with a small worker pool and a reusable keep-alive HTTP client.
• Server automatically falls back to legacy one-command-at-a-time transport for Agent < 1.4.0.
• Empty Mapping values now keep Value= in the vMix request, so generated empty roster rows can clear old title text.
• Match switch, language switch, full Mapping apply and Применить Input use batch transport when Agent 1.4.0 is connected.

Нормализованная статистика — build 30

Добавлено отдельное SQL-хранение матчевой статистики команд, сезонной статистики игроков/команд, строк standings и powerplay/rank. Исходный RAW Stat2TV сохраняется. Подробности: NORMALIZED_STATISTICS_DB.md.

Проверка: GET /api/hockey/database/statistics-status?tournament_id=<ID>.