up

2026-10-17 21:21:03 +07:00
parent 1d4028b183
commit 402e212332
15 changed files with 1017 additions and 24 deletions
@@ -0,0 +1,141 @@
+# SCREEN-008 — Кандидат 0.2.0-rc.1 и общая приёмка
+
+Кандидат собирается без доверенной подписи Windows/macOS и без notarization.
+Для macOS используется техническая ad-hoc подпись (`identity: "-"`), без
+сертификата разработчика и без подтверждения доверия Apple. Это не снимает
+предупреждения Gatekeeper/SmartScreen. Публикации и автообновления нет.
+
+## Сборка и проверка архива
+
+Используются существующие electron-builder и package-lock.json. В CI выбран
+Node.js 24.15.0; локальную фактическую версию записывает build-info.json.
+Зависимости устанавливать через `npm ci`, Electron — существующей командой
+`npx --no-install install-electron --no`. Нужен ffmpeg с libx264; выполнить
+`npm run media:generate` перед упаковкой. Все тесты и сборки запускать
+последовательно: команды build/test/smoke пересобирают общий dist-electron.
+
+```sh
+npm run type-check
+npm run lint
+npm run lint:css
+npm test
+npm run smoke
+npm run dist -- --linux --win --x64 --arm64 --publish never
+```
+
+Последняя команда — локальная кросс-сборка Linux/Windows. На соответствующей
+целевой ОС можно собрать один вариант, например:
+
+```sh
+npm run dist -- --mac --arm64 --publish never
+npm run dist -- --win --x64 --publish never
+npm run dist -- --linux --arm64 --publish never
+```
+
+Матрица ручного workflow builds.yml: macos-15-intel, macos-15,
+windows-2025, windows-11-arm, ubuntu-24.04, ubuntu-24.04-arm.
+Commit/push и запуск workflow выполняет владелец. Workflow загружает только
+артефакты выполнения, не создаёт GitHub Release. macOS здесь локально не собирается.
+
+Архивы находятся в release/; имена содержат версию, ОС и архитектуру. После
+упаковки hooks проверяют версию приложения, ELF/PE/Mach-O архитектуру, наличие
+пульта/preload/синтетических медиа, отсутствие проектных тестов, секретов и
+посторонних файлов приложения. app.asar включает автоматически упакованные
+production-зависимости; тестовые скрипты сборки туда не входят.
+
+В resources/build-info.json записаны Git revision, dirty, версии Node/Electron/
+electron-builder/ffmpeg, хеш lockfile и SHA-256 app.asar, WAV и MP4. Хеш app.asar
+покрывает весь упакованный код. После повторного чтения самого архива создаются
+`<archive>.build-info.json` и `SHA256SUMS-<варианты текущего запуска>`. Старые
+архивы из release/ не подмешиваются. Это сведения о происхождении и целостности,
+а не цифровая подпись или гарантия побайтового совпадения разных сред сборки.
+
+Повторная проверка явно выбранных архивов:
+
+```sh
+npm run verify:release -- release/evening-detective-screen-0.2.0-rc.1-linux-x64.tar.gz
+```
+
+В Linux проверить соответствующий SHA256SUMS через `sha256sum -c`, в macOS —
+`shasum -a 256 -c`, в PowerShell — сравнить `Get-FileHash -Algorithm SHA256`
+с нужной строкой manifest. Проверять суммы после передачи файла на целевой компьютер.
+
+## Установка и обновление
+
+| Платформа | Установка |
+| --- | --- |
+| macOS Intel/Apple Silicon | Распаковать соответствующий ZIP, перенести .app в Applications. |
+| Windows 11 x64/ARM64 | Распаковать весь ZIP в отдельную постоянную папку и запустить EXE. |
+| Ubuntu 24.04 / Debian 13 x64/ARM64 | Распаковать tar.gz с сохранением прав и запустить evening-detective-screen. Под Wayland нужен XWayland. |
+
+Сначала закрыть старое приложение. Сохранить старый каталог приложения отдельно,
+распаковать новый в другую папку и запустить его. Не распаковывать поверх работающей
+копии и не переносить пользовательские файлы в resources/app.asar. Идентификатор,
+название приложения и формат существующих пакетов не меняются. userData находится
+отдельно от программы и сохраняется при замене папки приложения.
+
+Ожидаемые стандартные каталоги userData: `%APPDATA%/evening-detective-screen`
+в Windows, `~/Library/Application Support/evening-detective-screen` в macOS,
+`$XDG_CONFIG_HOME/evening-detective-screen` либо `~/.config/evening-detective-screen`
+в Linux. Путь зависит от имени приложения/профиля среды; test/dev могут использовать
+другое имя. Архивы и журналы не содержат пользовательскую папку. Перед обновлением
+можно сохранить её копию локально; файл connection/credentials.bin содержит секреты,
+его не отправлять в отчётах и не переносить на другой компьютер как способ входа.
+
+Если ОС предупреждает о неподписанной сборке, проверить источник и SHA-256,
+использовать штатную процедуру разрешения запуска согласно политике компьютера.
+Не отключать Gatekeeper/SmartScreen и защиту ОС глобально. Результат запуска
+конкретного неподписанного кандидата обязательно записать в таблицу приёмки.
+
+## Локальные журналы
+
+`userData/logs/diagnostic.jsonl`, `diagnostic.1.jsonl`, `diagnostic.2.jsonl`:
+не более трёх файлов по 1 МиБ. Формат — JSON Lines, UTC-время и фиксированные
+коды событий. Записываются версия/платформа, запуск/выход, открытие/причина закрытия
+показа, ошибки медиа, смена состояния связи и результат подготовки материалов.
+
+В журнал не передаются сообщения Error.message, URL запросов, токены, пароли,
+серверные ответы, тексты игры или данные участников. Повторные статусы связи и
+позиции проигрывателя не пишутся каждую секунду. Если журнал недоступен, показ
+продолжается; в stderr появляется только код SCREEN_LOG_UNAVAILABLE.
+Для отчёта достаточно этих файлов и таблицы приёмки; весь userData не прикладывать.
+
+## Автоматическая проверка упакованного приложения
+
+```sh
+npm run smoke:packaged -- release/linux-unpacked/evening-detective-screen
+```
+
+Скрипт запускает настоящий бинарник с отдельным временным userData и тестовыми
+no-sandbox/mute-audio/disable-gpu и локальным DevTools-портом. Он проверяет интерфейс,
+preload, локальную выдачу Range, восстановление пакета/результатов/настроек,
+два перезапуска без автопуска и нормальный выход с журналом. Вторым аргументом
+можно передать предыдущий бинарник для прогона обновления на том же тестовом профиле.
+Скрипт не пересобирает dist-electron. В CI этот smoke выполняется на Linux x64
+под Xvfb; он не заменяет физический звук, проектор и native fullscreen.
+
+## Общий сценарий на каждом стенде
+
+1. Записать версию/архитектуру сборки, SHA-256, ОС, CPU/RAM, дисплей/переходник,
+   аудиовыход и форматы. Выполнить инструкции SCREEN-001 и SCREEN-004: по 30 запусков
+   каждого проверяемого формата/аудиовыхода, физические медиана/p95; порог ≤150 мс
+   относится только к M1 с 16 ГБ RAM.
+2. Войти, скачать настоящую игру, выбрать её и открыть показ на реальном внешнем
+   дисплее. Проверить восемь режимов, план, текст/кириллицу, таймер, музыку и результаты
+   по SCREEN-005/006. Проверить телефон в Safari iPhone и Chrome Android через сайт.
+3. Отключить сеть на час и пройти полный показ с музыкой, перемоткой, таймером и
+   сменой сцен. Готовые файлы не должны требовать сети; пульт/технические ошибки
+   не должны появляться на проекторе. Записать стабильность и ошибки журнала.
+4. Выполнить SCREEN-007: переподключение проектора, смена параметров дисплея,
+   fullscreen, автоматический/принудительный сон, кабельный/USB/HDMI звук.
+   Восстановление требует явного открытия; медиа остановлены, таймер на паузе.
+5. Вернуть сеть. Старая команда телефона не отменяет локальное действие;
+   новая команда применяется. Завершить игру и сохранить результаты с датой снимка.
+6. Перезапустить приложение без сети: выбранная игра/снимок доступны, окно показа
+   закрыто, звук не начинается. Заменить папку приложения новой сборкой с тем же
+   пользовательским профилем и повторить проверку сохранности данных.
+7. Передать заполненную таблицу результатов и безопасные журналы. Отметить каждый
+   непройденный пункт отдельно. До результатов всех стендов SCREEN-008 остаётся
+   IN_PROGRESS; открытые SCREEN-001/004/007 не объявляются завершёнными.
+
+Шаблон: [SCREEN-008_RESULTS.md](SCREEN-008_RESULTS.md).