# Установка и обслуживание

## Подключения и запуск

`HOCKEY_DATABASE_URL` — удалённая PostgreSQL с хоккейными данными и сессиями.
`WFL_DATABASE_URL` — база аккаунтов для авторизации; приложению нужен доступ чтения
соответствующих учётных записей. Производственный режим не использует SQLite.
Перед запуском выполните `python check_remote_database.py`.

Основные параметры окружения:

```env
HOCKEY_DATABASE_URL=postgresql+psycopg://USER:PASSWORD@HOST:5432/hockey
WFL_DATABASE_URL=postgresql+psycopg://USER:PASSWORD@HOST:5432/wfl
HOCKEY_AUTH_MODE=wfl
STAT2TV_LOGIN=...
STAT2TV_PASSWORD=...
```

Stat2TV также может использовать существующий локальный файл credentials.
Не заменяйте реальные секреты значениями из примера. Для HTTPS используйте
соответствующую настройку secure-cookie и прокси с поддержкой WebSocket.

Штатная команда сервера — `python -m uvicorn app:app --host 0.0.0.0 --port 8000`.
Используйте один worker без `--reload`: назначения Agent, WebSocket и очереди живут
в памяти процесса. Увеличение workers требует отдельного общего брокера состояния.
`GET /api/health` — публичная проверка процесса, не проверка всей цепочки до vMix.
`/api/hockey/database/status` проверяет подключение БД и может требовать авторизацию.

Для существующего Linux-сервиса основной скрипт — `deploy_hockey.sh`;
`deploy.sh` оставлен совместимым коротким входом. Перед использованием проверьте
в скрипте адрес репозитория, каталог, имя сервиса и путь environment-файла.

## Обновление и восстановление

1. Остановите эфирные команды/службу в согласованное окно.
2. Сохраните копию проекта и резервную копию PostgreSQL.
3. Сохраните `.env`, `settings/local/` или внешний `HOCKEY_UI_DATA_DIR`,
   локальные credentials/PIN, настройки mapping, `agent/agent_config.json`,
   `khl_site/data/` и пользовательские материалы.
4. Замените код, установите зависимости, проверьте БД, затем запустите сервис.
5. Проверьте авторизацию, два независимых матча, зрителя, Agent и титры vMix.

Обновление кода не требует сброса пользовательских настроек. Root-файлы
`settings/ui_builder_*.json` — начальные значения для миграции, а не активный UI.
Действующие настройки находятся в `settings/local/` либо абсолютном каталоге
`HOCKEY_UI_DATA_DIR`. Перед сменой этого каталога остановите сервер и перенесите
туда содержимое текущего рабочего каталога настроек.

Для BUILD190 обязательно повторите установку `python -m pip install -r requirements.txt`:
добавлена база часовых поясов `tzdata` для Windows. Agent.exe заменять не требуется.
Три целочисленных поля публикации Mapping добавляются существующим механизмом
миграции схемы. После запуска проверьте `/api/health`: версия `2026.10.21.1`.
Для обновления существующей VM используйте пакет только изменённых файлов;
полный архив содержит снимок настроек из присланной копии и предназначен для
восстановления/новой установки. Не заменяйте им более свежие настройки эфира.

История UI сохраняется при реальном изменении конфигурации, максимум 40 копий
на тип после сохранения. Старые backup-файлы переносятся один раз: служебный маркер
`.ui_backups_migrated_v1.json` предотвращает их повторное появление после удаления.
Черновик и опубликованная версия восстанавливаются отдельно через редактор.

## Хранение журнала

По умолчанию журнал хранится в `logs/`, отдельно от PostgreSQL матчей и WFL.
При необходимости задайте `HOCKEY_LOG_DIR` абсолютным путём к постоянному диску.
Процессу службы нужны права на создание/запись файлов в этом каталоге.

Файлы разделены по московским календарным месяцам. Хранятся текущий и предыдущий
месяцы: в октябре — сентябрь и октябрь; с 1 ноября сентябрь удаляется. Очистка
выполняется при старте и автоматически при смене даты, без перезапуска сервера.
Старые файлы удаляются только внутри выделенного каталога журнала; произвольные
файлы и символические ссылки не затрагиваются.

Запись идёт через ограниченную очередь отдельным потоком, чтение и выгрузка —
вне основного цикла HTTP/WebSocket. В журнале показаны счётчики очереди, потерь
при перегрузке и ошибок чтения/записи. При ненулевых счётчиках проверьте доступное
место, права каталога и нагрузку диска. Журнал не обещает сохранение каждой записи
при аварии диска/принудительном завершении процесса.

Доступ к просмотру и скачиванию требует аккаунта администратора. Время хранится
в UTC, фильтры и отображение используют Europe/Moscow. Не открывайте сам каталог
`logs/` через веб-сервер статических файлов.

## Скорость веб-интерфейса

HTML и данные API всегда обновляются. Скрипты и стили с версией в URL кэшируются
браузером; при изменении сборки/содержимого URL меняется. Ответы сжимаются GZip,
если браузер поддерживает его. Reverse proxy должен сохранять Content-Encoding,
Vary и Cache-Control; не задавайте общий публичный кэш для API.

Независимые запросы запуска выполняются параллельно. Runtime не строит список
всех полей для редактора на каждом live-обновлении, а несколько внешних обновлений
данных в одном кадре объединяются в одну перерисовку. Движок таймеров и немедленные
операторские команды продолжают работать отдельно.

## Безопасная очистка копии VM

Остановите сервер и Agent. Сначала просмотрите план:

```bash
python cleanup_project.py --dry-run
```

Применение:

```bash
python cleanup_project.py --apply
```

Утилита удаляет только bytecode в известных пакетах, старый `agent.log.1`,
проверенную старую неиспользуемую копию UI и резервные копии из `settings/backups/`,
которые уже идентично перенесены в `settings/local/backups/` и имеют маркер миграции.
Активный `agent.log`, `settings/local/`, секреты, конфигурация Agent и данные КХЛ
не удаляются. Изменённая старая копия UI автоматически сохраняется.

Исторические документы удаляются только при совпадении имени из allowlist и SHA-256
с копией в `docs/history.zip`. Изменённые пользователем старые инструкции сохраняются.

Одинаковые старые XML заменяются жёсткими ссылками: их имена, байты и пути в БД
сохраняются. Файлы снимков после этого следует считать неизменяемыми.
Если файловая система не поддерживает hardlink, соответствующий шаг пропускается.
ZIP-распаковка может снова создать отдельные копии; очистку можно повторить на VM.

Новые XML сохраняются по hash, одинаковые данные не создают новые файлы.
XML не удаляются по возрасту: на них ссылается история PostgreSQL. Для полного
архивирования уникальных XML требуется отдельно согласованная политика БД.
Автоматически чистятся только самостоятельные `*_games_discovery.json`:
сохраняются минимум 40 последних, более старые удаляются после 30 дней.

## Проверки

После обновления выполните целевые проверки mapping/прав/нескольких матчей и
`python -m pytest tests/test_build190_mapping_delivery.py tests/test_mapping_publications.py tests/test_program_log.py tests/test_web_observability.py tests/test_storage_maintenance.py tests/test_stage1_match_access.py tests/test_stage2_ui_storage.py`.
Старые тесты с жёстко заданными историческими номерами сборок требуют отдельной
актуализации; результат такого теста сам по себе не доказывает сбой эфира.
Живой vMix и рабочая PostgreSQL должны проверяться на отдельном прогоне перед эфиром.