6.1 KiB
跨端兼容与变更记录
规则
- 设备版本取设备自己的 VERSION，App 版本取 Android 工程独立版本，BLE 协议主次版本独立编号。
- 主版本相同的兼容新增通过 capabilities 宣告；旧 App 忽略未知可选字段，不发送未知能力命令。
- 删除／重命名命令、改变单位／含义、强制字段变化或加密线格式改变是破坏兼容；需新的主版本或保留旧版本适配。不能直接让旧 App 错误控制设备。
- 驱动内部实现变化但对外契约不变，登记“无需 App 更新”和验证依据；不能以“驱动没改”为由忽略业务协议破坏。
- 没有用户 App 迭代指令时，只记录待办，不擅自修改或发布 App。
- 每次跨端变更填写：需求编号、设备改动、协议版本、受影响 App、兼容策略、实际验证、待办、是否已有用户 App 授权。
当前基线
| 变更 | 状态 | 协议 | 移动端影响 | 授权与验证 |
|---|---|---|---|---|
| 首次 BLE 控制器、公共业务层、WiFi 扫描、网页连接提示 | 设计已确认，功能待实施 | 计划 1.0 | 新建 Android 首版，未来 iOS 复用 | 用户已明确授权首版；尚未完成设备与 APK 验收 |
| 视觉检查门禁 | 文档约束 | 无协议变动 | 普通 UI／BLE 开发不强制实屏；确需视觉检查必须先询问启动方式 | 用户明确要求；适用于本轮及后续 |
后续登记模板
2026-09-26，WEB-PERFORMANCE-MODE／DEPLOY-OTA-KERNEL-RECOVERY：设备 REST 的 /api/ota/status 增加可选 kernel_recovery 状态，/api/status.system.performance_mode.last_error 对缺失 cpufreq 给出具体原因；已有字段和 BLE 协议不变。旧 App 忽略新增 REST 字段，无需 App 更新。本轮仅改设备端；本机和实机验证结果以本次交付记录为准。
2026-09-25，MOBILE-RECONNECT／MOBILE-ERRORS：App 增加连接／扫描代次隔离，主动断开取消未完成命令，清理失效画面与状态缓存；轮询收到业务拒绝时保留连接。模拟平台仅编入 commonTest，通过真实分片／RPC 层测试旧回调、传输失败、未完成操作取消后的恢复。协议不变、设备不需更新；本轮首版授权内实施，真机结果另行归档。
2026-09-25，DEVICE-MOBILE-SETTINGS／CONFIG-WIFI：实机静态网络含多个 DNS，nmcli 返回逗号分隔而旧解析仅按换行，读回配置不能直接保存。修复设备 NetworkManager 解析，保持 DNS 数组契约；网页／App 共同受益，协议不变，无需 App 功能升级或另发版本。当前已授权首版联调；需设备部署及原网络重新应用验证，结果见当日归档。
2026-09-25，MOBILE-CONNECTION／MOBILE-RECONNECT：实机日志证实缓存 MTU 回调早于实际交换完成，提前服务发现会停滞；Android 改为等待实际协商值，再启动一次服务发现，保留 2 秒后备启动。设备端、协议线格式与驱动未改变，无需重新部署核桃派。Android 13 的生产 Controller 三页读取、短暂后台保持、30 秒后台释放及前台重连实测通过（115.718 秒）；完整持续复测与 Activity 语义测试继续进行。用户明确授权 root 切换专用手机蓝牙，已关闭并恢复成功。
2026-09-24，MOBILE-RECONNECT／MOBILE-ERRORS：Android 修复内部通信超时被视为主动取消而残留连接状态的问题；GATT 建立失败仅在握手前针对同一设备有限重试。对厂商重复 MTU 回调去重服务发现，接收上限保守限制为请求值 247。设备业务契约与协议版本不变，不重放写命令。用户已授权本轮 App 实现及断线排查；验证状态以测试结果归档为准。
首版联调补充：session.open.receive_mtu 为可选字段，缺省 23，声明手机实际接收分片上限。真实环境曾出现 Android MTU=247、BlueZ 回调 MTU=517，导致下行大分片丢失；现采用应用声明与 BlueZ 上限的较小值，ServerHello 固定按 MTU 23 分片。协议主版本保持 1，缺省行为可供未发送此字段的客户端使用。本轮用户已授权 Android 首版修改，Python／Kotlin 同步实现；真实 Android 13 只读会话及断开重连测试通过，尚未最终发布。
变更日期：
需求编号：
设备侧变化：
协议主次版本及能力：
受影响的 App 版本：
兼容策略：
验证证据（通过／未验证／不适用）：
移动端待办：
用户是否明确要求 App 迭代：
2026-09-25 验收补充
Android 断线清理与旧扫描回调隔离已通过模拟及 Activity 真机回归；UI 新增预览确认时间／过期提示、开机默认内容回读和临时密码可见开关。沿用既有 frame.get、content.default.get 等接口，设备协议主版本不变。DHCP 不再提交残留静态 DNS。昵称长度文档对齐已实现的 40 字符上限。网页文案生成索引同步，部署清单包含 ui-copy.json，不影响显示驱动。连续 BLE 读取完成后第二次连接出现过状态 62，保留失败记录并改为重新扫描后复测，不宣称根因已证明。
网页 WEB-MOBILE-PRESENCE 修正：首次载入已连接状态仅更新顶栏，不提示新的连接事件；之后检测到会话代数变化才短提示。只改网页事件判断，不改协议、App 或驱动，设备功能时间随本次可部署修复更新。
后续升级安装路径：ota_components 在存在移动端安装脚本时即使没有 FRP 载荷也进入持久系统组件事务，备份并恢复蓝牙配置、项目 drop-in、启用／屏蔽及运行状态；旧日志保持原行为。35 项组件／生命周期本机测试通过；真实完整 OTA 尚未执行，本轮不导出包。协议与 App 无需因此改变。
2026-09-26 四栏优化
用户明确要求 App 迭代。App 0.2.0 / code 3：四栏、设备记忆、中文 WiFi 设置、关于与本地设置；旧记录通过后续握手迁移。设备 library.list 对齐持久顺序，task.get 增加可选 error_code；协议主版本 1，旧 App 忽略新字段。无驱动修改，无新板端依赖，不导出 OTA／IMG。实际验证结果另行归档。