matrix-screen-controller/整体开发需求/03_移动端接入需求.md

# 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，不输出原始命令错误或密码。