feat(android): add native display and embedded announcements
This commit is contained in:
@@ -1,39 +1,51 @@
|
||||
# Android 公示屏 APK
|
||||
# Android 原生公示屏 APK
|
||||
|
||||
这是景区排队叫号系统的原生 Android 薄壳，只承载两个公开页面：
|
||||
这是景区排队叫号系统的原生 Android 大屏应用。应用直接请求公开展示接口并使用 Android Views 绘制页面，不再加载网页，也不依赖 Android System WebView。
|
||||
|
||||
- 总览页面：`https://queue.nianxx.cn/admin/display`
|
||||
- 单项目页面：`https://queue.nianxx.cn/display/{项目编号或公示 Token}`
|
||||
## 页面与数据流
|
||||
|
||||
- 默认打开总览页，对应 `https://queue.nianxx.cn/admin/display` 的业务数据。
|
||||
- 总览每 5 秒请求 `GET /api/display/overview`，展示项目卡片；总览状态不会创建播报任务。
|
||||
- 点击或使用遥控器确认项目卡片后，进入该项目详情，对应 `/display/{项目编号或公示 Token}`。
|
||||
- 项目详情每 3 秒请求一次 `GET /api/display/{identifier}/snapshot`。同一份快照同时更新界面并进行新叫号检测，不会重复请求。
|
||||
- 返回键从项目详情回到总览；在总览再次返回会退出应用。
|
||||
- 支持以 `https://queue.nianxx.cn/admin/display` 和 `https://queue.nianxx.cn/display/{identifier}` 作为 Android 深链启动。
|
||||
|
||||
## 现场能力
|
||||
|
||||
- 无浏览器地址栏的沉浸式展示，并保持屏幕常亮
|
||||
- 总览页面只展示项目状态，不进行语音播报
|
||||
- 单项目页面由 APK 每 3 秒读取公开快照接口，发现新叫号批次后调用系统中文 TTS
|
||||
- 每次叫号由 Android 原生层连续播报三次，并使用系统媒体音量通道
|
||||
- 接管项目卡的网页全屏请求，返回键退出全屏
|
||||
- 支持上述两个 HTTPS 页面作为 Android 深链
|
||||
- 仅允许 `queue.nianxx.cn` 的公开公示路径，阻止后台、员工端、外域和明文 HTTP 导航
|
||||
- 网络、证书或中文语音引擎异常时显示原生提示
|
||||
- 原生浅色景区大屏界面：总览自适应项目网格，详情显示当前叫号、四项统计和四行等候预估。
|
||||
- 固定横屏、沉浸式全屏并保持屏幕常亮；布局使用 dp/sp 和可用窗口尺寸，适配 1920×1080 横屏及不同显示密度。
|
||||
- 支持触摸、遥控器方向键、确认键和清晰的焦点状态。
|
||||
- 有缓存数据时，断网不会清空大屏，而是在顶部显示连接状态和上次更新时间；首次加载失败可直接重试。
|
||||
- 预告超过四行时每 6 秒翻页，3 秒数据刷新不会重置当前页。
|
||||
- 首次进入或从后台恢复时，第一份项目快照只建立叫号基线，避免重复播报屏幕上已有号码。
|
||||
- 发现新叫号后使用 APK 内置普通话音频和媒体音量通道连续播报三遍；快速连续叫号时按批次顺序排队，确保每批都完整播报三遍。
|
||||
- 播报通过流式 `AudioTrack` 输出并申请临时媒体音频焦点，避免与电视上的其他媒体源同时混播；若其他应用持续占用音频焦点，本次播报会失败并提示检查播放源。
|
||||
- 离开项目页或应用进入后台时，立即停止轮询和当前/待播语音。
|
||||
|
||||
APK 仍依赖线上服务和 Android System WebView，不会把实时队列数据离线复制进安装包。叫号检测和播报都由 APK 原生层负责，不依赖线上网页是否包含语音代码；普通浏览器访问单项目页面时不会播报。
|
||||
## 横屏兼容说明
|
||||
|
||||
应用通过 `screenOrientation="landscape"` 固定横屏。Android 16（API 36）默认可能在 `sw600dp` 及以上大屏忽略方向限制，因此 `MainActivity` 同时声明 Android 16 提供的临时兼容属性，使 targetSdk 36 的专用公示屏继续使用横屏兼容模式。
|
||||
|
||||
该兼容属性从 targetSdk 37 起不再生效；升级 targetSdk 前需要重新验证目标设备策略。设备厂商、设备所有者或桌面窗口模式仍可能覆盖应用方向请求。
|
||||
|
||||
## 设备要求
|
||||
|
||||
- 系统已安装并启用支持简体中文的文字转语音引擎
|
||||
- 设备媒体音量已打开
|
||||
- Android System WebView 可以访问 `https://queue.nianxx.cn`
|
||||
- 推荐 1920×1080 横屏。
|
||||
- 叫号音频已内置在 APK 中，无需安装或启用系统中文 TTS 引擎。
|
||||
- 设备媒体音量已打开，音频输出路由已连接到大屏扬声器。
|
||||
- 设备能够通过 HTTPS 访问 `https://queue.nianxx.cn`。
|
||||
|
||||
## 构建
|
||||
|
||||
需要 JDK 17+ 和 Android SDK 36（Build Tools 36.1.0）：
|
||||
需要 JDK 17+、Android SDK 36 和 Build Tools 36.1.0：
|
||||
|
||||
```powershell
|
||||
$env:ANDROID_HOME = 'C:\Users\你的用户名\AppData\Local\Android\Sdk'
|
||||
.\gradlew.bat testDebugUnitTest lintDebug assembleDebug
|
||||
```
|
||||
|
||||
可安装 APK 位于 `app/build/outputs/apk/debug/app-debug.apk`。Debug APK 适合现场安装验证；正式发布前应使用单位自有密钥生成签名 Release APK。
|
||||
可安装 APK 位于 `app/build/outputs/apk/debug/app-debug.apk`。当前版本为 `versionCode 9`、`versionName 1.5.2`。
|
||||
|
||||
## 安装与深链验证
|
||||
|
||||
@@ -41,3 +53,5 @@ $env:ANDROID_HOME = 'C:\Users\你的用户名\AppData\Local\Android\Sdk'
|
||||
& "$env:ANDROID_HOME\platform-tools\adb.exe" install -r .\app\build\outputs\apk\debug\app-debug.apk
|
||||
& "$env:ANDROID_HOME\platform-tools\adb.exe" shell am start -a android.intent.action.VIEW -d 'https://queue.nianxx.cn/display/YYHHC'
|
||||
```
|
||||
|
||||
Debug APK 适合现场安装验证；正式发布前应使用单位长期保管的 Android 签名证书构建 Release APK，以便后续安全升级。
|
||||
|
||||
Reference in New Issue
Block a user