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. Откройте показ вручную. Приложение применит текущую серверную сцену и музыку,
   включая воспроизведение. До готовности нового файла прежнее содержимое канала
   сохраняется. Все медиа читаются только с локального диска.
6. Перед выездом дождитесь полной подготовки без ошибок и проверьте игру без сети.
   Офлайн доступны только фактически скачанные файлы.

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

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

На чистом профиле адрес сервера заполнен: `https://evening-detective.crabs-games.art`.
Приложение направляет запросы этого сайта на `https://evening-detective-api.crabs-games.art`.
Сохранённый адрес имеет приоритет; для локального сервера можно вручную указать
`http://127.0.0.1:8090`.

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

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

### Редактирование плана

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

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

Кнопки «Показать», переходы назад/вперёд и управление текущим шагом работают
локально сразу. При наличии связи действие отправляется на сервер для остальных
привязанных экранов. Без сети показ продолжается по последней копии; статус
предупреждает о неподтверждённом обновлении. Офлайн-команды не накапливаются:
после восстановления связи принимается текущее серверное состояние. Прошлые
локальные переходы на сервер не отправляются.

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

Основное медиа определяется активным шагом плана экранов.
В «План музыки» выберите плейлист и трек для воспроизведения.

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

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

### Редактирование музыки

В «План музыки» доступны создание, переименование и удаление плейлистов,
добавление MP3 до 64 МиБ через системный диалог и удаление треков.
Выбор плейлиста для редактирования не меняет играющую музыку.
«Использовать в игре» назначает выбранный плейлист игре в остановленном состоянии.

Переставляйте треки кнопками ↑ / ↓, затем нажмите «Сохранить порядок».
«Отменить» возвращает серверный порядок. До сохранения или отмены нельзя
добавлять и удалять треки. При перестановке текущий файл продолжает играть;
следующий трек выбирается по новому порядку. Если состав треков изменился
на сервере, отмените черновик и повторите перестановку по актуальному списку.
Назначенный игре или сценарию плейлист удалить нельзя. Изменение состава,
порядка треков, режима завершения и удаление активной или приостановленной группы
требуют остановки музыки во всех использующих её играх; переименование доступно.

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

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

### Текст, QR-код, команды, таймер и результаты

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

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

## Связь с сервером

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

Приложение постоянно принимает изменения сцены, текста, таймера и музыки.
Первый ответ после подключения, открытия окна или восстановления сети применяется
как текущее состояние сервера. Одинаковая версия не запускает медиа повторно.
Команды локального пульта при доступной сети отправляются на сервер и относятся
ко всем привязанным экранам. Выключение всего звука остаётся локальной настройкой.

При явном подключении игры звук назначается этому экрану, локальный mute
выключается, основной канал и музыка устанавливаются на 100%.
Дальнейшие изменения сервера применяются как обычно; восстановление связи
без повторного подключения игры громкость не сбрасывает.

Назначение звука экрану меняется отдельно через сайт или «Назначить звук этому
экрану». Оно отключает звук остальных экранов по правилам сервера. При отсутствии
связи отображается последнее подтверждённое назначение.

Без сети продолжайте локально. После её возврата серверное состояние заменяет
локальное; накопленные локальные действия не отправляются. Точная синхронизация
позиций ограничена данными существующего API. «Отключиться» сразу прекращает
получение состояний и сохраняет отключение локально, затем пытается отвязать экран
на сервере. Если сервер не подтвердил отвязку за пять секунд, появится уведомление;
после возврата сети и перезапуска экран останется отключённым до нового подключения.

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

| Ситуация | Действия ведущего |
| --- | --- |
| Нет сети | Продолжайте локально. После возврата сети приложение примет текущие экран и музыку сервера. |
| Проектор отключился, изменилось разрешение или произошёл сон | Прочитайте причину в пульте, восстановите дисплей/выход звука, выберите внешний экран и явно откройте показ. Медиа остановлены, работающий таймер сохранён на паузе. |
| Нет звука | Проверьте выход и 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).

При ошибке подключения игры сообщение указывает запрос: описание игры, план
экранов или музыка. Таймаут, отмена, ошибка адреса и отказ соединения различаются.
Ошибка сессии требует повторного входа, а не проверки сети. В `diagnostic.jsonl`
событие `request-error` содержит только шаблон пути и разрешённый код причины;
пароли, токены, содержимое ответа и полные адреса туда не записываются.

Подробности ошибки видны прямо в пульте: операция, метод и путь API, статус HTTP
или безопасный код сетевого сбоя. Если JSON имеет неверную структуру, сообщение
показывает поле (включая индекс элемента), ожидаемый и фактический тип, например:
`Описание игры · GET /api/games/7: Некорректный ответ API: поле game.scenario.story — ожидалось объект, получено массив`.
Содержимое ответа, значения полей, токены и stack trace не отображаются.

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