91 lines
10 KiB
Markdown
91 lines
10 KiB
Markdown
# 跨端兼容与变更记录
|
||
|
||
## 2026-10-09 手机会话取消设备 WiFi 开机提示
|
||
|
||
需求：`DISPLAY-WIFI-INDICATOR`、`CONFIG-WIFI`、`DEVICE-MOBILE-SESSION`。设备在现有加密 `session.open` 成功后取消本 boot 的 WiFi 提示，包含未联网及联网 IP；无需改屏，断开及服务重启不恢复，整机重启重新计时。会话失败不触发，取消与后台提交协调避免迟到查询恢复提示。通信协议、状态字段、依赖及驱动保持现有契约，无需 App 更新；用户授权设备修改、定向测试和部署，未授权 App 迭代或发布。本机及板端实际验证结果见本轮测试归档，未执行项目不得记为通过。
|
||
|
||
## WiFi 通信第一阶段 / App 0.3.0 (6)
|
||
|
||
协议 1.2 增量能力 wifi_transport；原 BLE 握手和命令不变。新增 BLE transport.offer/close、加密 WebSocket /ws/mobile 及 mobile.active_transport（ble/wifi/null）。旧 App 忽略新字段，新 App 对旧设备保持 BLE。App 新增网络与 API 37 局域网权限。设备无需新 Python/Debian 依赖，不改驱动；手工可回滚部署，不导出 OTA/IMG、不推进设备发布版本。
|
||
|
||
## 规则
|
||
|
||
- 设备版本取设备自己的 VERSION，App 版本取 Android 工程独立版本，BLE 协议主次版本独立编号。
|
||
- 主版本相同的兼容新增通过 capabilities 宣告；旧 App 忽略未知可选字段，不发送未知能力命令。
|
||
- 删除／重命名命令、改变单位／含义、强制字段变化或加密线格式改变是破坏兼容；需新的主版本或保留旧版本适配。不能直接让旧 App 错误控制设备。
|
||
- 驱动内部实现变化但对外契约不变，登记“无需 App 更新”和验证依据；不能以“驱动没改”为由忽略业务协议破坏。
|
||
- 没有用户 App 迭代指令时，只记录待办，不擅自修改或发布 App。
|
||
- 每次跨端变更填写：需求编号、设备改动、协议版本、受影响 App、兼容策略、实际验证、待办、是否已有用户 App 授权。
|
||
|
||
## 当前基线
|
||
|
||
| 变更 | 状态 | 协议 | 移动端影响 | 授权与验证 |
|
||
|---|---|---|---|---|
|
||
| 首次 BLE 控制器、公共业务层、WiFi 扫描、网页连接提示 | 设计已确认，功能待实施 | 计划 1.0 | 新建 Android 首版，未来 iOS 复用 | 用户已明确授权首版；尚未完成设备与 APK 验收 |
|
||
| 视觉检查门禁 | 文档约束 | 无协议变动 | 普通 UI／BLE 开发不强制实屏；确需视觉检查必须先询问启动方式 | 用户明确要求；适用于本轮及后续 |
|
||
|
||
## 后续登记模板
|
||
|
||
2026-09-27，DEPLOY-OTA-OFFLINE-CLOSURE／DEPLOY-OTA-CANDIDATE：设备端移除误加入的电脑测试专用 Paramiko 依赖，改为检查 OTA 离线依赖闭包并按实机验证的原字节候选发布 1.1.3。REST、BLE、驱动及移动端协议均不变；无需 App 更新或重新签名。实机试装和恢复结果以本轮验收记录为准。
|
||
|
||
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 只读会话及断开重连测试通过，尚未最终发布。
|
||
|
||
```text
|
||
变更日期：
|
||
需求编号：
|
||
设备侧变化：
|
||
协议主次版本及能力：
|
||
受影响的 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。实际验证结果另行归档。
|
||
|
||
## 2026-09-27 Android 0.2.1 界面优化
|
||
|
||
MOBILE-STATUS／DISCOVERY／PREVIEW：顶栏自动循环、扫描条目断开与连接保留、设备画面居中。仅修改手机界面及会话显示状态；协议1.0、设备接口、广播仲裁和驱动不变，不要求设备升级。不推进设备发布版本或 FEATURE_UPDATED_AT。
|
||
|
||
## 2026-09-29 Android 测试流程
|
||
|
||
新增按影响选测、场景运行器和独立模拟器 uiTest。仅测试基础设施和协作规则变化；产品 App、设备接口、协议、驱动及部署契约不变，不升级版本、不发布 APK，不改设备功能时间。旧无场景默认真机命令改为显式 --scenario；迁移命令见测试入口。
|
||
|
||
## 2026-09-29 内容图库缓存
|
||
|
||
DEVICE-MOBILE-LIBRARY-CACHE／MOBILE-LIBRARY-CACHE：设备协议 1.1 在主版本 1 下新增 `library_progressive`、`library.summary` 和 16×16 `library.preview`，保留既有 64×64 `library.thumbnail` 与旧目录契约。Android 0.2.2 使用分档缓存和渐进加载，旧设备回退现有方式；旧 App 可继续连接新设备。设备与 App 本轮均获用户明确迭代和部署授权。验证证据待本轮测试归档，不涉及驱动或当前帧输出。
|
||
|
||
兼容说明：原 mobile.transport 为 BLE 统计对象，保持原义；实际链路新增 active_transport，不改变旧字段类型。
|
||
|
||
## 2026-10-01 本机测试环境归属
|
||
|
||
项目专用 SSH/编辑器环境、Android 测试系统镜像与 AVD 迁入本机测试目录 `.local/`，搭建入口及锁定依赖进入源码管理，私有主机状态/临时材料不提交。Android 构建入口支持指向项目存储的短期 ASCII 联接；SSH 和 WiFi 测试私有路径改为工作区内。只改变测试基础设施；App、设备公共接口、协议、驱动和部署契约均不变，不发布产品 APK、不部署设备、不推进版本和 FEATURE_UPDATED_AT。
|
||
|
||
## 2026-10-09 网页多图层与扩展画布
|
||
|
||
需求：WEB-LAYERS、WEB-EXTENDED-CANVAS、WEB-LAYER-OVERFLOW、CONFIG-SCENE-V2。设备端内容场景升v2、模板schema v2、动图schema v3、配置v11；新增网页图层追加接口及可选192文字预览。公共库列表、缩略图、默认内容、播放和frame.get仍为64×64；RGB888和BLE/WiFi加密协议1.2不变。App不解析网页编辑场景，无需更新App，无Android真机回归。受影响的共享内容库、播放和手机协议由Python契约回归覆盖；具体通过数量及设备结果见本轮归档。无新板端依赖，不改驱动，不推进VERSION，不导出OTA/IMG。
|
||
|
||
## 2026-10-09 网页图层UI修正
|
||
|
||
修正颜色/复选框布局、不透明复制提示和退出图层移动；只影响网页DOM/CSS与编辑交互。scene/模板/动图/配置schema、设备REST/手机协议及驱动边界不变，App无需更新，无Android真机回归。沿用原子部署，保持VERSION，更新FEATURE_UPDATED_AT；验收证据单独归档。
|