03 移动端接入需求

WiFi 传输第一阶段（协议 1.2）

DEVICE-MOBILE-WIFI-TRANSPORT：BLE 为会话前提；加密 BLE 交付 WiFi 地址与一次性短期凭据，以实际连接和身份验证判定可用，不比较 SSID 或限制同子网。WebSocket 复用公共业务、单所有者与串行执行。
DEVICE-MOBILE-WIFI-LIFECYCLE：BLE 独立保活；蓝牙断开撤销全部通道，WiFi 失败回退 BLE。只读可重取，结果不明写入不得重放。旧通道与回调隔离。
WEB-MOBILE-PRESENCE：顶栏“连接设备：名称 · WiFi/蓝牙”，无会话“连接设备：未连接”；切换不重复通知连接。
DEVICE-MOBILE-SESSION：手机成功完成加密握手和有效 session.open 后，设备取消本次开机的 WiFi 提示（含断网提示及联网 IP）。无需业务写入，断开或服务重启不恢复，整机重启重新计时；协议和 App 不变。
TEST-MOBILE-WIFI-TRANSPORT：覆盖双端向量、安全、在途故障、实际网络恢复、权限与传输对照；模拟与真实证据分别记录。

本文件定义核桃派侧行为，手机产品需求与协议分别见 ../移动端相关内容/开发要求/移动端需求.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，不输出原始命令错误或密码。

2026-09-27 手机界面测试补充

TEST-MOBILE-INTEGRATION：Android 顶栏溢出循环、扫描条目按认证会话切换断开且重新扫描保留、两处预览居中，按 ANDROID-TEST-STATE／UI 做共享逻辑与 root 真机布局验收。设备接口、广播仲裁与驱动不变，不需要设备部署或实屏视觉检查。

按变更影响选择验证（当前规则，替代每轮全量要求）

TEST-MOBILE-INTEGRATION：矩阵是覆盖目录，不是每轮必跑清单。先记录直接和间接影响，再选择最低有效层级；无影响的页面、BLE、WiFi、性能和生命周期不重复执行。必要证据缺失记为未验证，不能写不适用。历史专项验收不构成后续每轮义务。

TEST-MOBILE-SELECTION：运行器显式选择场景，支持不访问设备的列表与预览；切网、控制写入、长轮询和蓝牙开关单独选择。模拟器使用测试 APK 内假平台运行实际界面，不连接核桃派；模拟结果不替代真实 BLE、厂商行为或 systemd 验证。

2026-09-29 内容图库渐进加载

DEVICE-MOBILE-LIBRARY-CACHE：BLE 提供轻量目录修订查询及 16×16 静态预览；既有 64×64 缩略图接口保持兼容。设备为预览建立可再生缓存，并在启动与内容修订变化后清理失效项，不删除用户资源。目录修订覆盖条目内容与顺序。

TEST-MOBILE-LIBRARY-CACHE：验证两档图尺寸、修订一致性、网页修改后的失效与清理、旧客户端兼容；真实 BLE 对比首次加载和未变化重连的图片请求与字节数。当前帧、显示输出和驱动不变，无需新增实屏视觉验收。

6.7 KiB Raw Blame History Unescape Escape