移动端需求

1. 产品与范围

名称：奇妙小屏幕。Android 首版为 BLE 控制器，支持 Android 8.0（API 26）以上。连接不要求核桃派已联网，也不要求手机与设备在同一 WiFi。设备、内容、设置为三个一级页面，中文为首版界面语言。

稳定编号	行为与合格标准
MOBILE-PLATFORM	KMP 与 Compose 共享业务、界面；Android 本次交付，iOS 平台实现及发布不在本次范围。
MOBILE-DISCOVERY	前台扫描项目 BLE 服务；显示昵称、固定短编号和信号强度；首次点击目标后免系统配对连接。
MOBILE-IDENTITY	用设备持久随机 ID 区分设备；设备昵称可改，短编号不变；手机昵称默认型号，可改。蓝牙地址仅作扫描时临时连接句柄。
MOBILE-CONNECTION	一机一连接、一设备一控制会话；连接暂停广播，断开恢复；握手无效或超时断开，连接成功以握手完成为准。
MOBILE-RECONNECT	前台自动尝试上次设备，失败回到可扫描状态，不改连其他设备；主动断开后本次前台会话不立即反复重连。
MOBILE-BACKGROUND	连续后台 30 秒释放 BLE，停止预览和轮询；设备继续原显示；30 秒内返回取消释放；系统杀进程由设备会话超时释放。
MOBILE-SECURITY	免连接密码，标准算法自动加密；拒绝无效协议，不承诺鉴别正版 App 或抵抗主动仿制／中间人。无任意 shell 或文件接口。
MOBILE-STATUS	设备页展示连接、版本、协议、实际刷新率／帧数／截止丢失／最后错误、资源、网络、电压与保护、性能模式、容量及当前内容；不可用字段显示原因，不伪装为零。
MOBILE-LIBRARY	读取用户静态模板、动图、演示内容；名称、类型、静态缩略图、空列表与失效项状态清晰；不编辑、复制、排序或删除内容。
MOBILE-PLAYBACK	选择播放；动画暂停／继续、跳转、沿用设备支持的固定倍速；过期资源或播放会话提示刷新，不控制已替换会话。
MOBILE-DEFAULT	设置开机默认会保存并立即播放，界面明确说明；失败遵循设备回滚语义，不虚报成功。
MOBILE-PREVIEW	相关页可见且已连接时，每 2 秒请求当前逻辑帧，支持手动刷新；最多一个在途预览，命令优先，显示最近成功时间和过期状态。
MOBILE-WIFI	由核桃派扫描网络，手机选择或手填隐藏 SSID；输入密码、DHCP／静态 IPv4、立即／下次开机生效；区分保存成功、正在连接、连接失败和实际在线。
MOBILE-WIFI-SECRET	不读取设备已存密码；保留密码是明确的“不更改”操作，不把空文本误作清空；本次输入可临时显示，提交后清理，日志和持久缓存不保存。
MOBILE-SETTINGS	网络提示、亮度、方向、允许刷新率、性能模式；字段仅提交本次修改，全部值由设备校验和回读确认。
MOBILE-WEB-COEXIST	网页和手机并用；最近成功操作生效；手机连接网页短提示加顶栏常驻手机名；初次打开网页也显示当前状态，不伪造新连接提示。
MOBILE-ERRORS	权限未授予、蓝牙关闭、设备忙、不兼容、断线、超时、冲突和失败可区分；操作有界结束并恢复控件，保留未提交草稿。
MOBILE-COMPAT	协议能力发现及主版本协商；新增可选字段不破坏旧 App；破坏契约的设备改动必须登记移动端影响。
MOBILE-RELEASE	App 独立版本，首版仅 debug APK；正式签名和后续 App 迭代必须用户明确要求。
MOBILE-TEST-PRIVACY	私有测试登记不进 Git；空白示例和脚本可提交；自动测试精确选择授权设备，证据脱敏。
MOBILE-VISUAL-GATE	一般前端／BLE 入口改动不要求实屏视觉检查；确需时先暂停询问用户如何启动，未经指示不启动采集或视觉程序，不切换实屏测试图案。

MOBILE-RECONNECT／MOBILE-ERRORS 补充：断线清除旧画面、状态、缩略图队列；重新连接从新会话读取。主动断开取消未完成操作，旧连接或旧扫描的迟到回调不得覆盖新连接。业务冲突／内容不存在等正常错误回复不等同于传输失效，不应仅因此断开已经认证的会话。

不在首版：绘画、资源编辑／上传／导出／删除、FRP 配置、OTA 上传、电压校准、应用商店、自动更新、云账户。缩略图与当前帧读取属于控制界面预览，不等于提供图案文件导出。

2. 交互规则

连接状态始终可见；设备忙不会强行踢掉另一个手机。断开不会清屏、停止动画或改变用户配置。
修改设备昵称需要已连接，修改手机昵称为 App 本地操作并同步当前会话；只显示普通文本，不作身份认证。
设备昵称 1–40 Unicode 字符，手机昵称 1–40 字符；首尾空白去除，拒绝控制字符；设备编号由持久 UUID 前 8 个十六进制字符构成，冲突时显示完整 ID。
模板列表保留设备现有顺序，分页读取；动图采用首帧静态缩略图，空动图不可播放。
WiFi 扫描不是由手机代扫，不额外读取手机 WiFi 凭据。首版支持开放网络与个人密码网络，企业 EAP 提示暂不支持；真实硬件支持能力由设备报告。
WiFi 切换不得依赖 HTTP 仍可达，进度经 BLE 查询；失败保留可再次修改入口，不自动替用户猜密码。
修改刷新率仅限设备允许的 15、20、30、45、60、80、100 Hz；方向限 0、90、180、270。其他范围沿用设备业务校验并通过协议能力公布。

3. 平台差异

项目	Android 本次	iOS 后续
UI／业务	共享 Compose、状态机、协议模型	复用共享模块，按平台适配布局
BLE	Android BluetoothGatt，串行 GATT 操作	CoreBluetooth，独立平台实现
权限	API 26–30 扫描定位权限与系统要求；31+ 附近设备扫描／连接权限，不索取后台定位	Info.plist 蓝牙用途描述，按 iOS 生命周期实现
后台	30 秒释放为上限目标；进程终止也能由设备释放	不假设后台持续运行，策略需未来真机确认
构建	Windows、Android Studio、Gradle、debug APK	macOS／Xcode、签名及真机测试，不声称当前已验证

4. 更新约束

需求变更先更新本表，再更新详细设计、协议和测试。设备更新不得自动修改 App；影响通信能力、驱动边界或部署行为时必须填写 跨端兼容与变更记录.md。首版开发是本次明确授权，不代表后续自动更新授权。

测试编号、执行位置和合格条件见 ../安卓app/如何安卓测试/README.md。阶段进度不是需求的一部分。

2026-09-26 四栏界面修订（替代同编号旧描述）

MOBILE-STATUS／PREVIEW：四栏为连接、设备状态、显示内容、设备设置。顶部小字显示设备昵称、代号及实际 WiFi 状态；两处预览统一“设备画面”与右侧手动刷新，正常时不显示刷新频率和确认时间，仅过期提示。删除运行状态和容量详情。
MOBILE-DISCOVERY／IDENTITY／RECONNECT：App 按完整 ID 记忆成功连接设备；保存列表长按重命名或忘记。只可重命名当前连接设备，忘记它则断开并取消自动重连。扫描可与已连接会话并行，首次和忘记后的设备只由手动选择连接；自动重连只尝试上次已记忆设备。切换先断开旧会话。
MOBILE-LIBRARY：列表使用设备保存的混合顺序；分页顺序变更返回冲突，App 重新读取完整列表。
MOBILE-WIFI／SETTINGS：亮度、中文方向；移除 App 刷新率／性能模式入口。WiFi 状态、默认收起的设置、提示秒数依次排列；SSID 右侧扫描，选择自动填入。DHCP 开启自动获取、关闭展开静态参数；仅立即生效，提交前确认。认证错误须有可靠设备原因，不把通用失败写成密码错误。
MOBILE-WIFI-SECRET：不回读原密码，“已设置密码”占位，原 SSID 留空保留，替换密码只驻留内存；取消确认不提交。
MOBILE-APP-SETTINGS：顶部三点菜单关于／软件设置，关于显示版本、构建编号及北京时间打包日期；手机昵称可离线修改并同步当前会话。
MOBILE-TEST-PRIVACY：本 App 调试所需测试权限可通过登记手机 ADB root 直接获取，无需重复询问；所有自动点击使用 root 并依据实时语义位置，禁止无障碍绕过。特殊情况或权限不足必须停止等待用户。视觉和物理门禁不变。

8.6 KiB Raw Blame History Unescape Escape