up

2026-10-17 21:53:17 +07:00
parent e8edaf342d
commit 35e579701a
4 changed files with 280 additions and 2 deletions
@@ -37,6 +37,15 @@ SCREEN-008 остаётся IN_PROGRESS до сборок macOS и аппара
 Новые задачи: `Новая задача: <описание>`.
 Commit и push выполняет только пользователь. Вложенные `.git` не изменять.
 ## Документация
 - Ведущему: [руководство пользователя](docs/USER_GUIDE.md) и
  [чек-лист площадки](docs/EVENT_CHECKLIST.md).
 - Проверяющему: [установка, обновление и общая приёмка](docs/SCREEN-008_ACCEPTANCE.md),
  [фактические результаты и открытые проверки](docs/SCREEN-008_RESULTS.md).
 - Разработчику: запуск и устройство приложения описаны ниже;
  [план](PLAN.md), [активные задачи](TASKS.md), [завершённые задачи](COMPLETED_TASKS.md).
 ## Запуск проигрывателя
 Нужны Node.js 24.15+ и ffmpeg с libx264 в PATH.
@@ -51,8 +60,8 @@ npm run dev
 ```
 До запуска подключите второй дисплей в режиме расширенного рабочего стола
-и назначьте экран компьютера основным. В пульте выберите
+и назначьте экран компьютера основным. В блоке «Дисплей показа» выберите
-его и откройте показ. Аудио и видео — синтетические локальные файлы длительностью
+внешний дисплей и нажмите «Открыть показ». Аудио и видео — синтетические локальные файлы длительностью
 60 секунд; бинарники находятся в игнорируемом fixtures/ и не входят в Git.
 Тестовый режим сохраняет отдельный выбор WAV/видео; игровые пакеты выбираются
 в разделе «Материалы показа». В блоке «Игра и сервер» доступны вход, список игр и загрузка материалов.
@@ -201,6 +201,12 @@ SCREEN-009 (LAN-пульт) отменена владельцем; ID не пе
  ожидается проектор. Зафиксированы три падения GPU-процесса (139), состояние UI
  требует подтверждения владельца. Подробности в docs/SCREEN-008_RESULTS.md;
  аппаратный PASS пока не выставлен.
 - Документация ведущего (2026-10-17): добавлены docs/USER_GUIDE.md и
  docs/EVENT_CHECKLIST.md — установка/обновление, подготовка игры, управление,
  офлайн и восстановление, журналы и чек-лист площадки. README содержит навигацию
  по ролям и однозначный выбор внешнего дисплея. Названия кнопок и поведение
  сверены с текущим UI; относительные ссылки и git diff --check — PASS.
  Код не менялся, новые аппаратные испытания не выполнялись.
 - Открыто: получить macOS x64/arm64 через workflow после commit/push владельцем;
  выполнить аппаратную матрицу, включая оба Linux-дистрибутива, час офлайн,
  проектор/звук/телефон и физические замеры на M1. Статус IN_PROGRESS до получения
@@ -0,0 +1,63 @@
 # Чек-лист площадки
 Для ведущего, работающего с подготовленной игрой. Подробности:
 [руководство](USER_GUIDE.md). Текущий кандидат — 0.2.0-rc.1;
 [аппаратная приёмка ещё открыта](SCREEN-008_RESULTS.md).
 ## До выезда
 - [ ] Выбран архив своей ОС/архитектуры, SHA-256 совпал, приложение запускается.
 - [ ] В «Игра и сервер» выполнен вход, нужная игра загружена до завершения.
 - [ ] В «Материалы показа» выбрана именно игра, а не тестовый режим.
 - [ ] Проверены обложка, шаги, вступление, видео, текст, таймер и нужные плейлисты.
 - [ ] Пробный показ и перезапуск без интернета подтвердили готовность локальной копии.
 - [ ] Если нужны результаты, сохранён доступный снимок и проверена его дата.
 - [ ] Подготовлены питание, проектор, кабели, переходники и аудиоподключение.
 ## До прихода игроков
 - [ ] Проектор подключён в режиме расширения; экран компьютера назначен основным.
 - [ ] В «Дисплей показа» выбран внешний дисплей, нажато «Открыть показ».
 - [ ] На проекторе материалы, на компьютере пульт; кириллица и изображение читаются.
 - [ ] В ОС выбран нужный аудиовыход. Пробный звук слышен физически, mute выключен,
  громкость основного канала и музыки подходит для помещения.
 - [ ] После подключения HDMI аудиовыход проверен повторно.
 - [ ] Для телефона подключено управление выбранной игрой, проверен номер экрана,
  связь с сервером и новая команда с сайта. Звук назначен нужному экрану.
 - [ ] Перед стартом выбрана нужная сцена, музыка и таймер в ожидаемом состоянии.
 - [ ] Компьютер подключён к питанию; крышка остаётся открытой.
 ## Во время игры
 - [ ] Проверять фактический показ и статусы; смена шага сама не запускает медиа/таймер.
 - [ ] Управлять музыкой отдельно; при речи уменьшать её громкость вручную.
 - [ ] При потере сети продолжать локальным пультом.
 - [ ] Перед закрытием показа при необходимости поставить таймер на паузу:
  обычное закрытие не прекращает отсчёт.
 - [ ] Не обновлять материалы выбранной игры при открытом показе.
 ## Если произошёл сбой
 - [ ] Прочитать сообщение пульта и записать время/последнее действие.
 - [ ] При отсутствии изображения проверить проектор, кабель, расширение рабочего стола
  и выбор внешнего дисплея; явно нажать «Открыть показ» после восстановления.
 - [ ] При отсутствии звука проверить системный выход, HDMI, mute и громкость обоих каналов.
 - [ ] После аварии проверить остаток таймера на паузе; медиа запускать явно.
 - [ ] После возврата сети дождаться связи и отправить новую команду телефона.
 - [ ] При повторном сбое сохранить журналы и сведения по
  [руководству](USER_GUIDE.md#журналы-и-обращение-за-помощью).
 ## После игры
 - [ ] При доступной сети после завершения игры обновить снимок результатов,
  проверить таблицу и время снимка.
 - [ ] Остановить основной канал и музыку, закрыть показ и приложение.
 - [ ] Сохранить сведения о сбоях; не передавать пароли, токены и весь профиль.
 - [ ] Сохранить нужные пакеты; удалять только ненужные локальные копии.
 ## Для ответственного за приёмку
 Этот чек-лист не заменяет часовой офлайн-прогон, проверки сна/переподключения
 и физические замеры. Выполните [полный сценарий](SCREEN-008_ACCEPTANCE.md#общий-сценарий-на-каждом-стенде)
 и заполните [результаты](SCREEN-008_RESULTS.md#отчёт-одного-стенда).
 Программные миллисекунды пульта не являются физической задержкой.
@@ -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).