98 lines
12 KiB
Markdown
98 lines
12 KiB
Markdown
# 移动端需求
|
||
|
||
## WiFi 传输第一阶段
|
||
|
||
- MOBILE-WIFI-TRANSPORT：两端已有 WiFi 且 BLE 会话有效时自动探测，实际可达即启用，不比较 SSID 或限制同子网。IPv4 首版不包含热点、WiFi Direct、独立 WiFi 或云连接。
|
||
- MOBILE-WIFI-FALLBACK：WiFi 使用期间 BLE 每 2 秒保活；WiFi 失败回退，2/5/10/30 秒退避再试；蓝牙断开整体断开。网络事件撤销旧通道；静默故障目标 10 秒内回退。
|
||
- MOBILE-CONNECTION-TRANSPORT：连接页当前设备“已连接”左侧显示“连接状态：蓝牙/WiFi”，列表一致、窄屏换行。权限拒绝仍可蓝牙控制，提供局域网授权入口。
|
||
- MOBILE-WIFI-SAFETY：身份绑定当前 BLE 会话；不重放结果不明的写操作，回读并提示。后台立即停预览，30 秒释放全部连接。
|
||
|
||
## 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 并依据实时语义位置，禁止无障碍绕过。特殊情况或权限不足必须停止等待用户。视觉和物理门禁不变。
|
||
|
||
## 2026-09-27 界面修订
|
||
|
||
- MOBILE-STATUS：顶栏长文字自动向左无限循环（30 dp/秒、每轮间隔1秒），短文字静止；菜单固定，完整语义文字保留。
|
||
- MOBILE-DISCOVERY／CONNECTION：握手成功后扫描条目显示已连接及断开按钮；再次扫描保留当前连接条目，旧扫描信号不作实时信号。断开、失败和异常清理会话关联；其他条目仍可连接，连接期间禁止重复操作。
|
||
- MOBILE-PREVIEW：两处设备画面、标题、等待与过期提示按整个卡片居中，刷新按钮固定右侧；标题预留对称空间，放大字体不与按钮重叠。
|
||
|
||
## 按影响选测
|
||
|
||
MOBILE-TEST-SELECTION：先评估直接及共享依赖影响，再选最低有效层级。纯逻辑用 JVM；普通 UI 用独立模拟器；真实通信、权限/后台厂商差异用定向真机。未改页面不因发布新功能重复测试。root 仅约束登记真机输入，模拟器使用标准 Compose 测试 API。测试授权不等于每轮执行义务。矩阵及证据格式见测试入口。
|
||
|
||
## 2026-09-29 内容缓存
|
||
|
||
MOBILE-LIBRARY-CACHE：显示内容的全部条目先请求 16×16 预览，再在预览阶段全部完成一次尝试后逐项取得 64×64 完整画面。缓存按持久设备 ID、类型、条目 ID、修订和档位隔离；连接、进入内容页及内容页前台定期检查设备目录修订，未变复用本地目录与图片，变化后先完整读取目录再清理失效缓存。离线不显示旧列表。单张失败显示占位且不阻塞后续项目；旧设备退回现有图库读取方式。当前设备画面不参与此缓存。
|
||
|
||
MOBILE-CACHE-CLEAR：软件设置显示内容缓存大小，确认后仅清空内容目录与图片缓存；不清除昵称、设备记忆、当前帧或设备内容。内容页前台才进行图片后台补传，控制操作优先，切页、后台、断线停止队列。
|
||
|
||
|
||
## Android 动画浏览（2026-10-10）
|
||
|
||
MOBILE-LIBRARY-ANIMATION：先全部低清首图，再完整低清动画，再高清；可见动图按原时长循环，动画及部分下载纳入内容缓存。
|
||
MOBILE-IMAGE-VIEWER：图库和设备画面点击全屏、缩放、返回；未完成时自动提示“开始下载当前图像”，提升当前项优先级，关闭后 300 ms 恢复普通队列，后台立即暂停。浏览不改变设备输出。
|