hockey_new/README.md

# Hockey Stat2TV / UI Builder — BUILD 2026.07.20.13

## Базы данных

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

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

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

## Настройка

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

```env
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`.

## Запуск

```powershell
START.bat
```

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

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

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

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

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

```json
{
  "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 формируется для постоянного канала аккаунта и языка:

```text
/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/...` оставлены как совместимые алиасы, чтобы существующие проекты не перестали читать данные.

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

```text
/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>`.