up

2026-10-17 21:53:17 +07:00
parent e8edaf342d
commit 35e579701a
4 changed files with 280 additions and 2 deletions
@@ -0,0 +1,200 @@
+# Руководство ведущего
+
+Приложение «Вечерний детектив» хранит подготовленные материалы на компьютере
+и показывает их на проекторе. Пульт работает на основном экране компьютера.
+Телефон отправляет команды через существующий сервер сайта; без сети
+управляйте показом с компьютера.
+
+Перед мероприятием используйте [чек-лист площадки](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).