hockey_new/docs/OPERATOR.md

# Работа оператора

## Подготовка эфира

1. Войдите под своей учётной записью и откройте нужный матч.
2. На компьютере с vMix запустите Agent и проверьте связь отдельно с сервером и vMix.
3. Проверьте назначение Agent: свой аккаунт, выбранный матч и нужный проект vMix.
4. В Mapping выберите сохранённую конфигурацию и проверьте Inputs, имена полей,
   строки и источники SQL. Сохраните изменения, затем кнопкой ▶/↻ рядом с профилем
   выберите его для нужного Agent. ✓ обозначает опубликованную текущую версию.
5. Проверьте тестовое обновление счёта, выбранного игрока, удаления и численного состава.
   Перед эфиром убедитесь, что на титрах появились ожидаемые данные.

Привязка к Input использует его имя и доступную сохранённую идентичность проекта.
Переименование Input и замена GT-полей требуют проверки соответствий Mapping.
Номер Input может изменяться при перестановке Inputs.

## Готовность к эфиру

Выберите матч и нужный Agent, затем откройте **«Диагностику»** в верхней панели.
Блок **«Готовность к эфиру»** относится именно к этой паре: матч и устройство
указаны рядом с результатом. Проверьте назначение, связь Agent/vMix, структуру
титров, опубликованный Mapping, наличие связанных полей и последние подтверждения.

«Не проверено» означает, что подтверждения пока нет; ошибка или предупреждение
содержит причину. Пустая очередь команд сама по себе не подтверждает отправку
всех титров. Поля, которыми управляет native Countdown, сохраняются отдельно и
не включаются в число применённых значений Mapping. Общий статус сервера в этой
же панели описывает доступность сервера.

Сводка читает текущее состояние. Она не применяет Mapping и не отправляет тестовые
команды в vMix. Последняя успешная обработка данных и подтверждение Agent имеют
своё время; актуальность внешнего источника проверяйте отдельно. Перед эфиром
проверьте сами титры, счёт и работу native Countdown в vMix. После перезапуска
сервера или переподключения устройства прежнее подтверждение теряет силу.
Правка конфигурации источников также требует нового результата полной обработки;
успех до правки не подтверждает изменённую конфигурацию.

## Несколько участников и матчей

Каждый участник входит в свою учётную запись. Разные матчи должны иметь разные
активные назначения Agent; проверяйте имя устройства и матч перед передачей в vMix.
Одинаковый шаблон Mapping можно использовать для разных устройств, но актуальный
контекст матча и выбранных игроков относится к конкретному каналу.

За каждым Agent закреплена отдельная опубликованная версия связей Mapping.
Сохранение шаблона не переключает остальные эфиры: ↻ означает, что появилась
новая версия, которую можно явно применить к выбранному Agent. Одновременное
сохранение устаревшего черновика выдаёт конфликт версии вместо перезаписи чужих
изменений. Удаление шаблона сохраняет уже опубликованные версии на устройствах.
SQL-источники остаются общими справочниками: их изменение влияет на все связи,
которые используют этот источник. Проверяйте такие изменения вне эфира.

В одном матче оператор управляет общим состоянием, зритель видит обновления.
Передавайте управление штатной кнопкой интерфейса. Вкладка зрителя не должна
служить резервным операторским окном без передачи прав.
Лимит параллельных матчей зависит от БД, источников и оборудования; фиксированного
гарантированного числа эта сборка не устанавливает.

## Счёт и составы

В режиме **SQL** панель счёта показывает текущие значения из БД матча. Если для
стороны настроен пользовательский SQL-ключ, используется его актуальный результат;
при отсутствии корректного результата берётся счёт матча из БД. Ноль — допустимый
счёт. Режим **«Ручной»** сохраняет значения оператора и не заменяет их обновлением БД.
Если у пользовательского SQL-источника включено автообновление, связанные поля
счёта обновляются с настроенным интервалом при работающем назначенном Agent.

При смене матча ответы прежнего выбора отбрасываются. Уже сохранённые составы
завершённого матча загружаются из БД без ожидания повторного внешнего импорта.
Если составов в БД ещё нет, их получение зависит от доступности внешнего источника.

## Таймеры и удаления

Первый запуск периода задаёт базовое время и запускает native Countdown vMix.
Пауза использует SuspendCountdown. При ручной правке времени новое значение должно
сразу появиться в vMix; переход периода возвращает его настроенную базу.
Регулярный период обычно 20:00, овертайм регулярного чемпионата 05:00;
плей-офф использует отдельное правило из настроек.

При добавлении удаления проверьте выбранного игрока, тип/длительность штрафа,
видимую плашку и численный состав. Снятие отложенного штрафа не должно снимать
плашку действующего удаления. Совпадающие/обоюдные штрафы обрабатываются правилами
численного состава; не заменяйте их ручным скрытием активного таймера.

Кнопки, последовательности и горячие клавиши настраиваются в редакторе интерфейса.
Открытие редактора требует права и PIN; обычный вход открывает рабочий экран.
Изменения публикуются отдельно от черновика. Не назначайте одну горячую клавишу
нескольким независимым командам управления таймером.

## Если данные перестали приходить

Проверьте связь сервера, Agent и vMix, назначение устройства, выбранный матч,
состояние Mapping и сообщения об ошибке доставки. Зафиксируйте время, устройство,
матч, Input и поле, которое не обновилось. Диагностика должна различать отсутствие
данных источника, разрыв Agent и ошибку применения команды в vMix.
Сохраните лог до перезапуска. Повторное применение Mapping может восстановить
передачу, но скрывает первопричину; сведения о сбое нужны для её проверки.

В BUILD190 значения считаются применёнными только после подтверждения Agent.
Временные ошибки безопасных установок текста/изображения/видимости получают
ограниченный повтор. После восстановления связи и получения структуры титров
синхронизация запускается автоматически. Работающие поля native Countdown при
полном обновлении Mapping не перезаписываются.

В BUILD192 Mapping передаётся небольшими пакетами с отдельным подтверждением
каждого поля. Ошибка нескольких полей больше не обрывает отправку остальных
титров. Сначала отправляется весь доступный остаток, затем выполняются ограниченные
безопасные повторы. При разрыве связи или смене назначения отправка прекращается;
после восстановления запускается синхронизация. Отказ отдельной HTTP-команды
vMix не считается доказательством потери связи со всей программой.
В BUILD194 новый Agent **1.5.5** получает команды одного Input одним пакетом,
если они помещаются в 500 команд и 48 КиБ. Большой титр делится на ограниченные
части. Сам vMix применяет HTTP-команды по отдельности: пакет не гарантирует
одновременную смену всех полей в одном кадре. Для кнопок и таймеров выделен
отдельный обработчик. При смене назначения прежняя очередь отменяется. Запуск native Countdown
защищает его поле от оставшихся команд старого массового обновления; сохранённые
таким образом поля учитываются отдельно от применённых команд.
Для этого режима обновите Agent.exe; со старым Agent остаются пакеты до шести
команд. Ошибки и отсутствующие данные показываются как неполное обновление.

В журнале выберите раздел `mapping`, нужный матч и Agent: итог показывает число
подтверждённых значений, попыток и повторов, а также Input, поле и причину ошибки.
Если HTTP-команда отклоняется постоянно, проверьте название Input и SelectedName
в загруженном проекте vMix; повторная отправка не исправляет неверную цель.

## Журнал программы

Кнопка **«Журнал»** в верхней панели доступна администратору. Для быстрого просмотра
с телефона откройте `http://АДРЕС_СЕРВЕРА:8000/logs` (либо тот же путь на вашем
обычном HTTPS-адресе) и войдите под своей учётной записью администратора.

Выберите «Сегодня», «7 дней», «Этот месяц» или «Все доступные». Можно указать
свои даты — конечная дата включается полностью. Время и календарные границы
отображаются по Москве. Фильтры позволяют выбрать уровень ошибки, раздел,
участника, матч, Agent или найти текст в сообщении и деталях. Порядок «Сначала
новые/старые» и переходы по страницам не меняют выбранные фильтры.

«Скачать TXT» создаёт читаемый файл для пересылки и просмотра; JSONL сохраняет
структуру событий для технического разбора. Скачивается весь выбранный период,
а не только открытая страница. Автообновление каждые 5 секунд включается отдельно
и приостанавливается при закрытии журнала/скрытии вкладки или просмотре старой страницы.

Журнал содержит входы/выходы, HTTP-запросы, действия участников с ограниченными
деталями, подключения Agent/vMix, отправки и подтверждения команд, обновления
источников, исключения и замеры браузера. Пароли, PIN, ключи, токены, cookies,
строки подключения БД и параметры SQL исключаются; большие payload ограничиваются.
Это эксплуатационный журнал, а не копия всех пакетов/таблиц базы.

Для медленного компьютера найдите раздел `browser`, событие `browser.ready`.
В деталях есть время ответа сервера, загрузки документа, получения конфигурации
и данных, первоначальной отрисовки и общей готовности экрана. Эти значения
позволяют сравнить два компьютера в одинаковом матче и сетевых условиях.

Для сравнения быстрого и медленного ПК откройте один матч и одну опубликованную
конфигурацию в одинаковой версии приложения. На каждом ПК повторите запуск
несколько раз, отдельно отметив первое открытие и обычные перезагрузки.
Запишите время, браузер и компьютер; в «Журнале» выберите соответствующий период
и участника, затем скачайте JSONL. Для разбора нужны события `browser.ready`
и соседние HTTP-запросы. Сравнивайте типичное время нескольких запусков:
ответ сервера, получение конфигурации/данных и отрисовку. Эти замеры описывают
загрузку экрана, а проверку готовности титров к эфиру выполняйте отдельно.