From 35e579701a9191461285269d1ef49049ac5285e4 Mon Sep 17 00:00:00 2001 From: Fedorov Vladimir Date: Sat, 17 Oct 2026 21:53:17 +0700 Subject: [PATCH] up --- README.md | 13 ++- TASKS.md | 6 ++ docs/EVENT_CHECKLIST.md | 63 +++++++++++++ docs/USER_GUIDE.md | 200 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 280 insertions(+), 2 deletions(-) create mode 100644 docs/EVENT_CHECKLIST.md create mode 100644 docs/USER_GUIDE.md diff --git a/README.md b/README.md index 6f18576..6369731 100644 --- a/README.md +++ b/README.md @@ -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/видео; игровые пакеты выбираются в разделе «Материалы показа». В блоке «Игра и сервер» доступны вход, список игр и загрузка материалов. diff --git a/TASKS.md b/TASKS.md index a80d97b..3422107 100644 --- a/TASKS.md +++ b/TASKS.md @@ -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 до получения diff --git a/docs/EVENT_CHECKLIST.md b/docs/EVENT_CHECKLIST.md new file mode 100644 index 0000000..5bc1447 --- /dev/null +++ b/docs/EVENT_CHECKLIST.md @@ -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#отчёт-одного-стенда). +Программные миллисекунды пульта не являются физической задержкой. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..f5a28a5 --- /dev/null +++ b/docs/USER_GUIDE.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).