bulid 63

REMOTE_DATABASE.md

@@ -0,0 +1,59 @@
+# Удалённая PostgreSQL-база хоккейного проекта
+
+Сборка работает **только** с удалённой PostgreSQL. Локальная SQLite отключена.
+
+## 1. Создать отдельную базу и пользователя
+
+Пример команд для администратора PostgreSQL:
+
+```sql
+CREATE USER hockey_app WITH PASSWORD 'CHANGE_ME';
+CREATE DATABASE hockey OWNER hockey_app ENCODING 'UTF8';
+\c hockey
+GRANT USAGE, CREATE ON SCHEMA public TO hockey_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO hockey_app;
+GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO hockey_app;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO hockey_app;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO hockey_app;
+```
+
+Если база и пользователь уже созданы, этот шаг не нужен.
+
+## 2. Настроить `.env`
+
+Скопируйте `.env.example` в `.env` и укажите реальные адреса:
+
+```env
+WFL_DATABASE_URL=postgresql+psycopg://postgres:password@localhost:5432/wfl_db
+HOCKEY_DATABASE_URL=postgresql+psycopg://postgres:password@localhost:5432/hockey
+```
+
+`WFL_DATABASE_URL` читает аккаунты WFL. `HOCKEY_DATABASE_URL` хранит все
+хоккейные матчи, справочники, статистику, настройки сессий и кэш API.
+
+## 3. Запуск
+
+При запуске программа:
+
+1. проверяет соединение командой `SELECT 1`;
+2. создаёт отсутствующие таблицы;
+3. добавляет новые неключевые поля при обновлении версии;
+4. прекращает запуск с понятной ошибкой, если PostgreSQL недоступен.
+
+Проверка после запуска:
+
+```text
+http://127.0.0.1:8000/api/hockey/database/status
+```
+
+В ответе должны быть `ok: true`, `backend: postgresql`, `remote_only: true`.
+Пароль базы в API и логах не показывается.
+
+## Состояние таймеров матчей
+
+Начиная с BUILD 2026.07.20.5 основной таймер и активные удаления сохраняются в
+`hockey_game_control_states` отдельно для каждого `game_external_id`. При первом
+запуске сборка автоматически добавит столбцы `timer_state_json` и
+`timer_state_updated_at`, если их ещё нет.