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`.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- В редакторе плана добавьте шаг «Текст», заполните текст и сохраните план.
  Нажмите «Показать» у этого шага. Переносы строк сохраняются.
- Для шага «Таймер» задайте надпись и длительность в секундах, сохраните план
  и покажите шаг. В активном шаге доступны «Старт», «Пауза», «Продолжить»
  и «Сбросить». При смене шага отсчёт продолжается в фоне;
  на нуле остаётся 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 не отображаются.

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