evening_detective_screen/docs/USER_GUIDE.md

# Руководство ведущего

Приложение «Вечерний детектив» хранит подготовленные материалы на компьютере
и показывает их на проекторе. Пульт работает на основном экране компьютера.
Телефон отправляет команды через существующий сервер сайта; без сети
управляйте показом с компьютера.

Руководство описывает текущие исходники и пересобранный Linux x64 0.2.0-rc.1.
Остальные архивы ещё содержат прежние подписи режимов и кнопки подключения
и не отображают новый отдельный статус назначения звука.

Перед мероприятием используйте [чек-лист площадки](EVENT_CHECKLIST.md).

## Версия и установка

Текущий кандидат — **0.2.0-rc.1**. Собраны архивы Linux и Windows для x64 и ARM64;
сборки macOS ожидаются. Аппаратная приёмка всех платформ ещё не завершена.
[Фактические результаты и ограничения](SCREEN-008_RESULTS.md).

Выберите архив под архитектуру компьютера: x64 для Intel/AMD, ARM64 для ARM.
У macOS Intel используется x64, у Apple Silicon — arm64. Требования первой версии:
Windows 11, macOS 13+, Ubuntu 24.04 LTS или Debian 13. Эти требования не означают,
что совместимость каждого стенда уже подтверждена.

1. Получите архив, соответствующий файл `.build-info.json` и контрольные суммы
   у ответственного за сборку. Сверьте SHA-256 после передачи на компьютер;
   [команды проверки](SCREEN-008_ACCEPTANCE.md#сборка-и-проверка-архива).
2. Windows: распакуйте ZIP целиком в постоянную папку, запустите EXE из неё.
   Linux: распакуйте tar.gz с сохранением прав файлов и запустите
   `evening-detective-screen` из распакованной папки. На Wayland нужен XWayland.
   Когда macOS-архив станет доступен, распакуйте ZIP и перенесите .app в Applications.
3. Доверенной подписи Windows/macOS и notarization нет. При предупреждении ОС
   проверьте источник и сумму, следуйте штатной процедуре разрешения запуска
   согласно политике компьютера. Не отключайте защиту ОС глобально.

Для готового архива установка Node.js, npm и ffmpeg не требуется.
Сохраните всю распакованную папку: одного исполняемого файла недостаточно.

## Дисплей и звук

1. Подключите проектор и включите в ОС **расширение рабочего стола**.
   Основным назначьте экран компьютера; зеркалирование для раздельных окон не подходит.
2. В настройках звука ОС выберите кабельный, USB или HDMI-выход и проверьте громкость.
   После подключения HDMI система может переключить выход на проектор.
3. В приложении, в блоке «Дисплей показа», выберите внешний дисплей.
   Если список пуст, проверьте кабель, переходник и режим рабочего стола ОС.
4. После выбора материалов нажмите «Открыть показ». Проверьте реальное изображение:
   на проекторе должны быть только материалы, а пульт — на компьютере.
   Блок «Текущий показ» показывает кадр окна показа с небольшой задержкой.

Звук воспроизводит окно показа; предпросмотр второго звука не создаёт.
Приложение использует аудиовыход ОС и не выбирает устройство самостоятельно.

## Подготовка игры при доступной сети

1. В «Игра и сервер» введите адрес сервера без пути, например адрес сайта
   с `https://`, email и пароль организатора, автора или администратора.
   Нажмите «Войти». Пароль вводите только в приложении, не отправляйте в отчёты.
2. При необходимости нажмите «Обновить список игр» и выберите игру
   в поле «Выберите игру для подготовки».
3. Нажмите «Загрузить материалы». Дождитесь завершения; при необходимости
   используйте «Отменить загрузку». Не выезжайте с незавершённой загрузкой.
4. В отдельном блоке **«Материалы показа» выберите подготовленную игру**.
   Загрузка и выбор игры на сервере сами по себе не выбирают пакет для показа.
   Статусы игр отображаются как «Черновик», «Идёт», «Пауза», «Завершена».
   Сообщение «Тестовый режим: синтетические аудио и видео» означает, что игровая
   копия не выбрана.
5. Откройте показ, проверьте изображения, вступление, видео и плейлисты.
   Отключите сеть и повторите пробный показ. Затем перезапустите приложение
   без сети и убедитесь, что выбранная игра доступна.

Если ОС не предоставляет защищённое хранилище, приложение предупреждает:
вход действует до закрытия приложения, но материалы сохраняются. После перезапуска
для серверного управления потребуется повторный вход; локальный пакет доступен офлайн.

Для обновления материалов закройте показ, выберите игру на сервере и нажмите
«Проверить изменения», затем явно «Загрузить материалы». Если файл заменили
по прежнему адресу, проверка изменений может этого не заметить — загрузите
материалы повторно. Новый плейлист тоже требует подготовки. Ошибка или отмена
обновления сохраняет прежнюю готовую копию.

## Проведение показа

В «План показа» выберите шаг, используйте «Предыдущий шаг» / «Следующий шаг»
либо переключатель «Режим показа». Доступны восемь режимов: «Обложка»,
«Введение», «Успехов», «Закрывашка», «Спасибо за игру»,
«Результаты», «Таймер» и «Текст». Переход к шагу или режиму сам не запускает
медиа и таймер. Дождитесь готовности; отправленная команда ещё не означает
успешного воспроизведения — смотрите статус и фактическое изображение/звук.

### Вступление, видео и музыка

В «Вступление и видео» выберите медиа; в «Музыка» — плейлист и трек.

| Управление | Действие |
| --- | --- |
| «Пуск с начала», «Повторить с начала» | Запускает выбранный ресурс с нуля. |
| «Пауза», «Продолжить» | Сохраняет позицию и возобновляет с неё. |
| «Стоп» | Останавливает и сбрасывает позицию. |
| «Позиция, секунды» → «Перемотать» | Меняет позицию, сохраняя паузу или воспроизведение. |
| «Громкость, %» | Меняет громкость отдельного канала. Начальное значение — 35%. |
| «Выключить весь звук» | Отключает оба канала, сохраняя их уровни громкости. |
| «Следующий трек» | Переключает музыку, сохраняя паузу или воспроизведение. |
| «Повторять плейлист» | После последнего трека возвращается к первому. |

Вступление и видео используют один основной канал и не звучат одновременно.
Музыка независима, автоматически не приглушается; перед речью уменьшайте её
громкость сами. Смена сцены останавливает основное медиа, музыка продолжает играть.
Смена плейлиста останавливает музыку. После последнего трека без повтора она завершается.

### Текст, таймер и результаты

- В «Текст и таймер» заполните «Текст для показа» и нажмите «Показать текст».
  До нажатия введённый текст не применяется. Переносы строк сохраняются.
- Заполните «Подпись таймера» и «Длительность, секунды», нажмите «Показать таймер».
  Затем используйте «Запустить таймер», «Пауза таймера», «Продолжить таймер»
  и «Сбросить таймер». При смене режима отсчёт продолжается в фоне;
  на нуле остаётся 00:00 без сигнала и автоматического перехода.
- После завершения игры при доступной сети нажмите «Обновить снимок результатов»
  в «Игра и сервер» (кнопка доступна после подключения управления).
  Выберите режим «Результаты» и проверьте дату снимка. Офлайн показывается
  последний сохранённый снимок, а не обновляемые серверные результаты.
  Неудачное обновление сохраняет прежний снимок.

«Закрыть показ» останавливает медиа, но **обычное закрытие не ставит таймер на паузу**.
При необходимости сначала нажмите «Пауза таймера». При смене пакета таймер сбрасывается.

## Управление с телефона

1. Войдите и выберите готовую игру в «Материалы показа».
2. Проверьте строку «Игра для управления»: это название локально выбранного
   пакета, независимо от игры в списке загрузки выше. Нажмите «Подключить управление
   этой игрой»; запишите показанный номер экрана.
   Откройте показ и дождитесь «Связь с сервером есть».
3. На телефоне откройте существующую страницу управления этой игрой на сайте.
   При необходимости назначьте звук экрану через сайт или кнопку
   «Назначить звук этому экрану». Это отключает звук других экранов игры
   по существующим правилам сервера. Статус назначения звука показывается отдельно
   от локального переключателя «Выключить весь звук». До подтверждения сервером
   назначение неизвестно; при закрытом показе или потере связи отображается
   последнее подтверждённое состояние.
4. Отправьте новую команду. Первое состояние после подключения, открытия окна
   или восстановления связи не повторяет старые команды.

Опрос сервера идёт раз в секунду при открытом показе. Быстрые команды между
опросами могут объединяться. Локальные команды компьютера действуют только
на его показ и не рассылаются другим экранам. Новая команда телефона может
изменить локальный показ. «Отключить управление» прекращает управление приложением,
но сохраняет привязку экрана на сервере. Для отвязки используйте сайт.
При отсутствии интернета пользуйтесь локальным пультом; прямого подключения
телефона к приложению по LAN нет.

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

| Ситуация | Действия ведущего |
| --- | --- |
| Нет сети | Продолжайте локально. После возврата сети дождитесь связи и отправьте новую команду с телефона. |
| Проектор отключился, изменилось разрешение или произошёл сон | Прочитайте причину в пульте, восстановите дисплей/выход звука, выберите внешний экран и явно откройте показ. Медиа остановлены, работающий таймер сохранён на паузе. |
| Нет звука | Проверьте выход и mute ОС, кабель/USB/HDMI, «Выключить весь звук», громкость канала, открытое окно и статус проигрывателя. Для команд телефона проверьте назначение звука экрану. |
| Ошибка подготовки сцены | Проверьте сообщение и нажмите «Повторить подготовку». При повторении проверьте пакет до продолжения игры. |
| Пакет повреждён или отсутствует файл | При доступной сети закройте показ и загрузите материалы заново. Для удаления выберите другой пакет или тестовый режим, затем «Удалить материалы» у нужной игры. Без сети восстановить отсутствующие байты нельзя. |
| Истёк вход или сессия экрана | Повторно войдите или подключите управление по сообщению пульта. Готовые материалы остаются на диске. |
| Приложение перезапущено | Выбранная игра и сохранённые результаты восстанавливаются. Откройте показ и запустите нужные медиа/таймер явно; их текущее выполнение не восстанавливается. |
| Пульт пуст или зависает при запуске | Запишите ОС, версию, симптомы и сообщения запуска, передайте отчёт. Не считайте такой запуск успешным. |

При открытом показе приложение запрашивает блокировку автоматического сна,
включая статичную сцену и паузу. Это не предотвращает принудительный сон
или закрытие крышки. После закрытия показа блокировка освобождается.

На текущем Manjaro-стенде при обычном запуске отмечены три падения GPU-процесса
с кодом 139; работоспособность пульта владельцем ещё не подтверждена.
Это наблюдение конкретного стенда, а не подтверждённый дефект всех Linux-сборок.
Тестовые флаги из автоматических проверок не являются штатной инструкцией запуска.

## Обновление приложения и завершение игры

Закройте приложение. Сохраните старую папку программы отдельно, распакуйте новую
в другую папку и запустите её на том же компьютере и под тем же пользователем.
Не заменяйте файлы работающего приложения. Пользовательские данные находятся
отдельно от программы; после обновления проверьте выбранную игру и результаты.
Не удаляйте профиль и не переносите секреты на другой компьютер.

«Выйти» отключает серверное управление, но не удаляет материалы и не прерывает
локальное воспроизведение. Для завершения остановите медиа, закройте показ
и приложение. «Удалить материалы» используйте только для пакетов, которые
больше не нужны: это удаление локальной копии.

## Журналы и обращение за помощью

Стандартные каталоги данных установленного приложения:

| ОС | Каталог |
| --- | --- |
| Windows | `%APPDATA%/evening-detective-screen` |
| macOS | `~/Library/Application Support/evening-detective-screen` |
| Linux | `$XDG_CONFIG_HOME/evening-detective-screen` или `~/.config/evening-detective-screen` |

При запуске с отдельным профилем путь отличается. Например, текущая ручная
проверка использует `release/acceptance-profile-linux-x64` в каталоге проекта.
Внутри профиля журналы лежат в `logs`: `diagnostic.jsonl`,
`diagnostic.1.jsonl`, `diagnostic.2.jsonl` — до трёх файлов по 1 МиБ.
Они содержат фиксированные события, а не полный текст ошибок пульта.

Передайте версию приложения и SHA-256 архива, ОС/архитектуру, оборудование,
время сбоя, последовательность действий, ожидаемый и фактический результат,
текст сообщения без секретов и диагностические файлы. Для аппаратной приёмки
заполните [шаблон отчёта](SCREEN-008_RESULTS.md#отчёт-одного-стенда).
Не отправляйте пароль, токены, `connection/credentials.bin` или весь профиль.

Разработчикам: [README](../README.md). Проверяющим:
[сборки и полная приёмка](SCREEN-008_ACCEPTANCE.md).