up

README.md

@@ -133,6 +133,42 @@ python3 tests/venue/smoke.py --verify
 Тестовые данные остаются в локальной базе; повторное создание запускайте только
 когда нужен новый набор. Дождитесь ответа `/api/test/ping` перед проверкой.
 
+### Учёт устройств (этап 12)
+
+Venue автоматически учитывает браузеры игроков, организаторов и экранов:
+`POST /api/devices/heartbeat` публично регистрирует подключение, а
+`GET /api/devices?gameID=<ID>` возвращает сгруппированные устройства организатору,
+администратору или разработчику. Фильтр необязателен; при его использовании
+список содержит только подключения выбранной игры. Панель состояния — этап 13.
+
+UUID браузерного профиля хранится отдельно от авторизации в localStorage;
+каждая вкладка и перезагрузка страницы создают новый UUID подключения.
+Без localStorage устройство получает временный UUID. Контекст страницы
+полностью заменяется при heartbeat и очищается при навигации. Организатор
+проверяется по JWT и правам игры, команда — по паролю и неотменённому участию,
+экран — по существующей сессии; игру команды и экрана определяет сервер.
+Credentials используются только для проверки и не сохраняются в реестре.
+
+Heartbeat отправляется сразу и каждые 20 секунд без параллельных запросов,
+а также при возвращении вкладки и восстановлении сети. Ошибки не блокируют
+игру и не показывают toast; повтор выполняется по интервалу. В prod ответ
+содержит `enabled=false`, после чего браузер прекращает heartbeat;
+список устройств в prod недоступен.
+
+Реестр хранится только в памяти backend: UUID, серверные времена,
+последние IP/User-Agent и проверенные ID игры/команды/экрана. IP не участвует
+в идентификации и авторизации. Связь актуальна строго менее 60 секунд;
+устройство доступно, если доступно хотя бы одно его подключение в списке.
+Подключения удаляются через 15 минут отсутствия при heartbeat или чтении.
+Предел — 1024 подключения; новые отклоняются с `ResourceExhausted`, если
+после очистки нет места. После перезапуска открытые браузеры регистрируются
+заново. Времена устройства вычисляются по сохранённым подключениям.
+
+«Нет связи» означает отсутствие heartbeat сайта, а не отключение от Wi-Fi.
+UUID обозначает браузерный профиль, а не физический телефон; очистка
+localStorage создаёт новое устройство. История посещений, полный URL,
+имена игроков, email и credentials в список не попадают.
+
 ### Прежние домены и HTTPS (этап 3)
 
 Подготовка в репозитории готова; проверка реального Cudy и Android/iPhone без WAN