同步移动端工程、设备控制改进与发布资料

2026-09-26 19:21:12 +08:00
parent 912ba432cf
commit 98eadc5c8b
137 changed files with 9274 additions and 85 deletions
@@ -2,6 +2,8 @@

 本文描述核桃派 ZeroW 在局域网内启动的网页配置端。这个网页是用户后续操作点阵屏幕的主要入口，当前阶段提供可叠加的像素与多文字内容编辑，以及纯色、诊断、清屏等独占设备测试能力。

+移动端是独立控制入口，设备接入要求见 `03_移动端接入需求.md`，手机需求见 `../移动端相关内容/开发要求/移动端需求.md`。网页布局调整不应影响 BLE 协议；设备功能改动须登记移动端兼容影响，不自动更新 App。
+
 项目默认一台核桃派只做这一件事：开机后自动启动网页服务和屏幕控制服务，同一局域网内的手机、电脑或平板通过 `http://核桃派IP:8080` 访问。

 ## 0. 需求编号索引
@@ -81,6 +83,7 @@
 | `CONFIG-PERFORMANCE-MODE` | CPU 性能模式请求 | 配置 v9 严格保存布尔字段 `performance_mode_enabled`，v8 升级与新设备均默认关闭；请求状态与实际 governor 分开报告。 |
 | `CONFIG-ANIMATION-PREVIEW-CONCURRENCY` | 动态缩略图并发上限 | 配置 v10 严格保存整数 `animation_preview_max_concurrent`，v9 升级与新设备均默认 `2`，只允许 `1..50`；系统设置在性能模式下方保存该值，并明确提示高并发会造成严重性能问题。 |
 | `DEPLOY-KERNEL-ROLLBACK` | AXP313A 候选内核与自动回滚 | 已验证候选以带摘要的预编译离线载荷交付；原内核、DTB、模块和 boot 脚本保持可启动，未通过内核、cpufreq、服务和 GPIO 健康检查时下一次自动回到原内核。 |
+| `DEPLOY-OTA-KERNEL-RECOVERY` | OTA 内核能力守护与轻量恢复 | OTA 前后比较内核、cpufreq、性能模式和候选启动标记；正常能力退化时回滚应用。已回退设备可更新应用，只有本机候选内核、DTB、模块及回滚设施通过固定摘要校验时，更新完成后才独立重启尝试恢复一次；失败不得自动重试，缺失或损坏材料只报告需要专用修复包，普通 OTA 不携带内核归档。 |
 | `DEPLOY-MEDIA-DECODERS` | 媒体解码依赖与隔离 | Debian 提供 FFmpeg/ffprobe/libheif；独立转换 unit 限制 CPU、内存、IO、设备和网络访问。 |
 | `WEB-SECURITY` | 局域网安全边界 | 第一阶段默认可信局域网，保留访问密码和上传限制扩展入口。 |
 | `WEB-ERRORS` | 日志和错误展示 | 后端记录关键事件，前端显示屏幕可用性和最近操作结果。 |
@@ -248,12 +251,12 @@ WantedBy=multi-user.target

 生产核桃派只运行本控制器及其必需的网络、监测和系统服务，必须使用可重复、可检查的专用主机配置：

- 默认启动目标为 `multi-user.target`；LightDM、`display-manager`、Xorg、桌面会话和蓝牙服务必须停用并屏蔽，不得在控制器运行时自动恢复。
+- 默认启动目标为 `multi-user.target`；LightDM、`display-manager`、Xorg 和桌面会话必须停用并屏蔽。移动控制器接入后允许必要的 BlueZ 与板载蓝牙初始化服务，按 `DEPLOY-MOBILE-BLE` 同步修改专用检查与部署；未完成该实施步骤前不得只手动解除屏蔽交付。
 - 板载音频必须通过 boot 配置关闭，`snd_bcm2835` 必须加入模块黑名单且在控制器启动前确认未加载；WirePlumber、PipeWire 及其用户级 socket 必须全局屏蔽，SSH 登录不得重新拉起音频会话。不得通过关闭矩阵硬件脉冲来兼容板载音频。
 - Wi-Fi、SSH、Avahi、`/dev/i2c-1`、Unit ADC、电压保护和 swap 必须保留；专用化不得修改无线网络、SSH 凭据、持久数据根或用户配置。
 - `scripts/dedicated_host.py check` 只读报告全部专用条件；`apply` 以幂等方式更新 boot 配置、模块黑名单和 systemd 启用状态，但不得自动重启。boot 配置更新必须原子替换、保留无关内容，不创建多代备份。
 - systemd 在启动应用前执行只读专用主机检查。任一硬件脉冲前置条件不满足时服务必须明确失败并记录原因，不能静默进入画面不稳定的软件脉冲模式。
- 未来需要声音时优先使用不加载 `snd_bcm2835` 的 USB 音频；未来确需桌面或蓝牙时，必须先修改本需求和专用主机脚本，再重新执行刷新率、资源负载和完整实屏验收。不得临时取消屏蔽后直接交付。
+- 未来需要声音时优先使用不加载 `snd_bcm2835` 的 USB 音频；恢复桌面或增加蓝牙必须同步需求、专用脚本，并检查刷新率、资源负载和输出帧。普通前端／BLE 入口改动不强制实屏视觉验收；仅驱动、扫描时序、底层输出改变或具体异常确需视觉证据时，先暂停询问用户如何启动，获明确指示后检查。不得自动启动摄像头、DroidCam、采集或视觉程序，也不得主动切换实屏测试图案。

 多语言文字部署还必须满足 `DEPLOY-FONTS`：

@@ -46,6 +46,8 @@

 ## 1. 设计原则

+移动端接入契约见 `03_移动端接入需求.md` 和 `../移动端相关内容/开发要求/设备通信协议.md`。手机通过公共控制服务使用本显示层，不能操作网页 DOM 或绕过保护直接访问驱动。驱动或输出契约变化必须登记移动端兼容影响；内部实现变化不等于需要 App 升级。普通前端／BLE 入口改动不强制实屏视觉验收，确需视觉检查须先停下询问用户如何启动并等待指示。
+
 ### 1.1 固定帧接口（`DISPLAY-FRAME`）

 项目内部提交到 `DisplayService` 和真实/模拟驱动时，统一使用 `64x64 RGB` 帧作为显示边界。网页场景中的透明文字等 `RGBA` 图层属于上层合成中间产物，必须先按顺序扁平化到 RGB，不能直接交给驱动。
@@ -0,0 +1,28 @@
+# 03 移动端接入需求
+
+本文件定义核桃派侧行为，手机产品需求与协议分别见 `../移动端相关内容/开发要求/移动端需求.md`、`../移动端相关内容/开发要求/设备通信协议.md`。当前是已确认的实施契约，不代表已部署。
+
+| 编号 | 要求 |
+|---|---|
+| DEPLOY-MOBILE-BLE | 启用必要 BlueZ 和板载蓝牙初始化服务，修改 dedicated_host 的 apply／check 及部署生命周期；不启用桌面或音频。依赖同步离线材料与摘要。 |
+| DEVICE-MOBILE-CONTROL | 网页与 BLE 共享公共业务服务；保留显示仲裁、低压保护、持久化和修订冲突；不经网页 DOM／HTTP 回环调用实现手机控制。 |
+| DEVICE-MOBILE-SESSION | 协议 1.0、自动加密、单连接／单控制会话、握手和活跃超时、连接暂停及断开恢复广播；无效请求不得执行。 |
+| DEVICE-MOBILE-IDENTITY | 持久随机 UUID 和可改昵称；短编号仅用于展示；旧设备升级保留身份，新镜像不得携带构建主机或测试设备身份。 |
+| DEVICE-MOBILE-COMPAT | 主版本与能力声明，兼容新增不破坏旧客户端；破坏变更登记移动端待办，不自动更新手机程序。 |
+| WEB-MOBILE-PRESENCE | 手机握手成功时网页短提示，连接期间顶栏常驻手机名，断开更新；初次加载只显示当前状态；昵称安全文本渲染。 |
+| DEVICE-WIFI-SCAN | NetworkManager 扫描并报告 SSID／安全类型／信号／当前连接，支持手动隐藏 SSID；参数化调用、有界等待、结果脱敏。 |
+| DEVICE-MOBILE-SETTINGS | 字段级变更与共享修订，网页也更新修订；旧草稿冲突不静默覆盖。WiFi 保存和连接完成分别报告，不返回已存密码。 |
+| DEVICE-MOBILE-LIFECYCLE | 蓝牙异常不拖垮显示服务；服务停启使会话与密钥失效，恢复后重新握手；真实 systemd 验证持久／运行目录边界。 |
+| TEST-MOBILE-INTEGRATION | 本机契约、网页回归、真机 BLE、WiFi、双手机、性能和独立重建分别记录；模拟结果不替代物理 BLE。 |
+
+DEVICE-MOBILE-SETTINGS 的网络往返约束：NetworkManager 读回多个 DNS 时须兼容逗号及换行分隔，接口统一返回独立地址数组，读回合法配置可保持密码重新提交。网页与 BLE 复用同一解析规则，不要求 App 为某一 nmcli 输出格式做适配。
+
+DEPLOY-MOBILE-BLE／DEVICE-MOBILE-LIFECYCLE 的升级约束：包含移动端安装脚本的后续 OTA，即使不携带新的 FRP 二进制，也必须进入系统组件事务。修改蓝牙前持久备份 main.conf、首次原配置副本、两个项目 drop-in、两个蓝牙服务的启用／屏蔽及运行状态；失败恢复原内容，删除本次新增文件，并恢复原服务状态。旧事务日志没有移动端字段时保持旧恢复行为。本轮只实现并验证该逻辑，不导出 OTA 或推进发布版本。
+
+设备当前屏幕和 ADC 已接好，不能冒充无负载测试。蓝牙启用前后检查刷新率、截止丢失、资源与输出帧；普通前端／BLE 接入不强制实屏视觉检查。驱动或底层输出改变、出现具体显示异常才提出视觉检查，先暂停询问用户下一步如何启动并等待明确指示；不自动开摄像头、DroidCam、采集或视觉测试程序，不主动切换实屏测试图案。
+
+测试步骤与映射见 `../测试相关资料/如何测试/核桃派点阵屏控制服务测试流程.md` 和移动端的 `安卓app/如何安卓测试/README.md`。本任务只手工部署，不自动导出 IMG／OTA；只有可部署功能修改才更新 FEATURE_UPDATED_AT，文档／登记脚本不改该时间。
+
+## 2026-09-26 接口修订
+DEVICE-MOBILE-CONTROL：BLE library.list 与网页共用 LibraryOrderStore 的用户混合顺序，演示条目保持固定位置；顺序参与分页修订。
+DEVICE-MOBILE-SETTINGS：WiFi 激活任务可选 error_code 为 AUTH_FAILED、NETWORK_UNAVAILABLE、IP_CONFIG_FAILED、UNKNOWN；原因来自 NetworkManager 的结构化状态，仅可靠认证证据可报告 AUTH_FAILED，不输出原始命令错误或密码。