hockey_new/UPDATE_KHL_CAREER_RU.md

# Обновление КХЛ и карьерной статистики

Сборка **2026.09.27.1**, пакет v5. Накопительное обновление поверх существующего проекта; предыдущие исправления v1–v4 включены.

## Что изменилось

### «Настройки → КХЛ сайт»

- Ручное обновление действительно запрашивает свежие страницы. Ранее HTML-кэш использовался без срока действия.
- Имена берутся из персональной карточки и структурированного списка КХЛ. В списке и карточке используется порядок **Имя Фамилия**. Навигация вроде «Конференция Запад» не считается именем.
- Кнопка **«Восстановить имена»** обновляет имена из списков без повторной загрузки тысяч персональных страниц и без удаления статистики.
- Если достоверного имени в старом файле нет, показывается «Имя не загружено» и отдельный ID. Выдуманные имена не подставляются. В исходном архиве повреждены имена всех 4 264 игроков; для их восстановления нужен успешный запрос списков КХЛ с вашего сервера.
- У тренеров: личные сведения, клубы из статистики, матчи, победы, поражения, процент побед, подробности по овертаймам/буллитам и итоговые показатели КХЛ. Вся навигация сайта больше не попадает в список клубов.
- У судей: роль, сезоны, матчи, штрафные минуты, среднее за матч и виды штрафов. Главные и линейные показаны отдельно. Штрафы относятся к командам в матчах с участием арбитра, а не к самому судье.
- Из фильтров убраны ложные сезоны из дат и строки copyright. Есть выбор сезона в карточке и раскрываемые подробности.
- Перечитывание данных сбрасывает кэш карточек в браузере. Ошибки HTTP, сессии и неподходящего ответа видны в панели.
- При частичном обновлении сохраняются прежние карточки, которые не удалось загрузить. Обновление текущих судей не удаляет историю остальных. Запись JSON атомарная.
- Три рабочих потока вместо десяти; пауза между запросами, ограниченный таймаут. После HTTP 403/429 новые сетевые запросы этой попытки прекращаются; после восьми последовательных сетевых ошибок — тоже. Ограничения сайта не обходятся.
- При недоступности новых матчей игрока доступный старый кэш показывается с предупреждением.

### Хранение в базе данных

**До обновления** модуль «КХЛ сайт» сохранял данные только в `khl_site/data/*.json`. Эти файлы не импортировались в основную PostgreSQL.

**После обновления** добавлены две таблицы:

- `hockey_khl_career_records` — карточки игроков, тренеров и судей, личные данные, карьерные итоги и нормализованная статистика персонала;
- `hockey_khl_import_state` — состояние импорта.

Таблицы создаются обычным механизмом запуска проекта, без удаления существующих таблиц. Импорт выполняется при старте, после фонового обновления КХЛ и по кнопке «Перечитать данные». Неизменённые записи повторно не записываются; ошибка импорта откатывает транзакцию. Исходные JSON остаются на месте.

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

### «Статистика → Карьера»

- По умолчанию показаны **все полевые игроки и вратари заявки на выбранный матч**, включая участников без найденной карьерной карточки.
- Галочка **«Все игроки текущего состава команды»** добавляет активных участников из сохранённого состава выбранного турнира. Учитываются идентификаторы клуба/команды турнира. Участники других сезонов и неактивные записи не добавляются.
- Можно выбрать обе команды или одну из них, искать по имени/номеру и сортировать таблицы, как в сезонной статистике.
- Режимы: вся карьера в КХЛ, регулярный чемпионат, плей-офф, Кубок Надежды. Это показатели за все клубы в КХЛ, а не только за нынешний клуб и не за все лиги мира.
- Полевые игроки и вратари показаны отдельно; по нажатию открывается подробная карточка.
- Есть дата источника, количество участников с данными и отметки отсутствия подтверждённой статистики. Прочерк не заменяется нулём.
- Совпадение числовых ID между разными источниками само по себе недостаточно: используются явный KHL ID/ссылка на фото КХЛ, либо ID с датой рождения, либо однозначное совпадение имени и даты рождения. Конфликт даты рождения и однофамильцы не объединяются автоматически.
- Итоги сайта имеют приоритет. При расчёте по сезонам складываются количественные показатели; проценты пересчитываются по суммарным величинам, средние взвешиваются. Неполный показатель не выдаётся за полный итог.
- Чтение идёт из общей БД. Внешний КХЛ при открытии «Карьеры» не запрашивается. Данные кэшируются в браузере; смена состава/фильтров и кнопка **«Обновить из БД»** обновляют выборку.
- Оператор-зритель может смотреть и выгружать данные. Доступ к управлению матчем от этого не меняется.

### Выгрузка для аналитики

**«CSV по составу»** выгружает выбранный охват (заявка либо полный состав), команду и этап. **«CSV всего состава»** выгружает полный состав выбранной команды/обеих команд. Поиск по имени не ограничивает CSV: в него попадают все участники выбранного охвата, в том числе строки без карьерных данных.

CSV: UTF-8 с BOM, разделитель `;`, названия колонок на русском, статус сопоставления, KHL ID, дата и URL источника, отдельные показатели полевых игроков и вратарей. Неприменимые значения пустые. Текстовые значения защищены от выполнения формул при открытии в таблицах.

Доступен и JSON: `GET /api/hockey/games/{id}/career?all_members=true&mode=all&language=ru`. Оба формата требуют входа в аккаунт. CSV: тот же путь с `.csv`, дополнительно `side=all|home|away`.

## Установка

1. Остановите приложение и сохраните резервную копию проекта и БД.
2. Распакуйте содержимое архива в корень существующего проекта, где находится `app.py`, с заменой файлов.
3. Запустите приложение обычным способом. Новые таблицы и импорт сохранённых данных выполнятся автоматически. Дополнительных Python-зависимостей нет.
4. Обновите страницу браузера. В «КХЛ сайт» проверьте надпись «В общей БД», затем нажмите **«Восстановить имена»**. При доступном сайте можно выполнить полное обновление.
5. Откройте матч → «Статистика» → «Карьера». Проверьте заявку, галочку полного состава и выгрузку CSV.

В пакете нет пользовательских настроек JSON, `.env`, БД, секретов Agent, кэша или собранных данных КХЛ. Настройки кнопок/шорткатов и ваши данные не заменяются архивом.

## Что проверено и что требует проверки у вас

Автоматические проверки и ограничения перечислены в `VALIDATION_KHL_CAREER_RU.md`. Живое чтение официального КХЛ из среды разработки подтвердить не удалось: прямой HTTP-запрос завершился таймаутом, запросы страниц через поиск вернули 403. Исправления не обещают доступность внешнего сайта; при блокировке видна причина и сохраняются прежние данные.

Производственная PostgreSQL, Windows и реальный vMix здесь не подключались. Изменения хранения проверены через SQLAlchemy на локальной тестовой БД; в рабочем приложении сохраняется требование PostgreSQL. Обновление не меняет протокол отправки таймеров vMix.

## Идеи для следующих изменений

- Сравнение двух игроков по карьере/сезону и показателям за матч для подготовки эфира.
- Подсказки о ближайших юбилеях: 100/500 матчей, 100 голов, 300 очков, с проверяемой ссылкой на источник.
- Проверка готовности перед эфиром: неполные составы, отсутствующие фото/имена, устаревшая статистика, доступность Agent и необходимых Input.
- Личная подборка статистических карточек для быстрого вывода в эфир владельцем матча; зритель может готовить подборку без управления титрами.