bulid 63

HOCKEY_DATA_ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# Архитектура хоккейных данных v20
+
+## Переиспользуем существующие модули
+
+Без дублирования продолжают использоваться:
+
+- UI Builder и Runtime;
+- хоккейная панель удалений;
+- общий таймерный движок;
+- триггеры и горячие клавиши;
+- публикация черновика;
+- PIN-вход в конструктор;
+- CSS-подсказки;
+- подготовленные JSON endpoints для vMix.
+
+## Серверные модули хоккея
+
+### `hockey_data/client.py`
+
+Авторизованные XML-запросы Stat2TV. Поддерживаются Basic, Digest и автоматический выбор.
+
+### `hockey_data/parser.py`
+
+Парсер списка турниров `tournaments.xml`.
+
+### `hockey_data/match_parser.py`
+
+Парсер расписания:
+
+```text
+{tournament_id}/schedule-{tournament_id}-live.xml
+```
+
+Один механизм поддерживает регулярный чемпионат и плей-офф. Поле `sscore` сохраняется как счёт серии.
+
+### `hockey_data/database.py` и `models.py`
+
+Проект работает только с удалённой PostgreSQL-базой, заданной через HOCKEY_DATABASE_URL. В базе разделены турниры, матчи, команды, игроки, составы, события и операторские сессии; локальная SQLite не используется.
+
+### `hockey_data/localization.py`
+
+Хранит RU/EN, выбирает язык веб-панели и резервное значение.
+
+### `hockey_data/service.py`
+
+Отвечает за:
+
+- синхронизацию турниров и расписания;
+- нормализацию XML;
+- выбор даты и матча;
+- правило «один пользователь — один активный матч»;
+- облегчённое секундное обновление выбранного матча;
+- остановку обновления после завершения;
+- формирование данных и ссылок vMix.
+
+### `hockey_data/auth_bridge.py`
+
+Точка подключения существующей авторизации ЖФЛ. Для окончательного соединения нужен код/схема текущих таблиц пользователей и сессий ЖФЛ.
+
+## Текущий поток данных
+
+```text
+Stat2TV tournaments.xml
+        ↓
+hockey_tournaments
+        ↓
+выбор турнира
+        ↓
+schedule-{id}-live.xml
+        ↓
+hockey_games
+        ↓
+выбор матча
+        ↓
+hockey_operator_sessions
+        ↓
+UI Builder + vMix JSON
+```
+
+## Следующие XML-слои
+
+После расписания требуется подключить:
+
+1. карточку выбранного матча;
+2. команды и составы;
+3. игровые события;
+4. удаления;
+5. подробную статистику.
+
+Когда будет найден детальный live-endpoint одного матча, секундное обновление можно перенести с полного расписания на компактный матчевый XML.