Improve controller behavior and update project requirements

2026-09-30 15:42:36 +08:00
parent 55374356ed
commit 071f06d365
52 changed files with 2205 additions and 335 deletions
@@ -0,0 +1,31 @@
+# 2026-09-29 “显示内容”两档图片与缓存验收
+
+## 变更与选测
+
+核桃派协议增加 `library.summary`、`library.preview` 和能力 `library_progressive`；`library.thumbnail` 仍是 64×64 PNG。板端按条目修订保存可再生 16×16 缓存并清理失效文件。App 按设备、条目修订和画质保存目录与图片，内容页先请求全部小图，再逐项请求完整图；有缓存时以目录修订确认复用。“当前设备画面”的 `frame.get` 路径不变，断线不提供离线列表。App 更新到 0.2.2／versionCode 5，设备 `VERSION` 保持 1.1.3，功能时间为 `2026-09-29T22:15+08:00`。
+
+直接影响目录、图片 BLE 请求、Android 私有文件缓存、内容页与软件设置。因此选择设备协议/缓存本机测试、sharedCore JVM、内容与设置的独立模拟器、登记手机的 `cache-storage` 和 `library-cache` 两个定向场景，以及 debug 构建/覆盖安装。未改动显示驱动、实际输出、WiFi、权限、后台策略或当前帧读取；这些专项按影响跳过。实屏视觉检查不适用，没有切换显示内容、测试图案或启动摄像头。
+
+## 实际结果
+
+| 验证 | 结果 |
+|---|---|
+| 板端本机 | `test_mobile_control.py` 19 项通过；与 `test_mobile_protocol.py` 合计的协议/控制定向测试 27 项通过。覆盖目录修订和顺序、16×16 PNG、旧 64×64 接口、失效小图清理、实际用户动画首帧和空动画。最终动画修复后重跑控制测试 19 项通过。 |
+| App 共享逻辑 | `:sharedCore:jvmTest` 通过；覆盖两轮顺序、重连复用、修订变化删除旧项、清空、旧设备回退及断线取消。 |
+| 独立模拟器 | API 35 的 content、settings、navigation 场景通过；内容页验证小图先于完整图、设置页清空确认。 |
+| 登记手机缓存存储 | `cache-storage` 通过；验证设备隔离、修订清理、损坏文件按未命中处理和清空。 |
+| 登记手机真实 BLE | `library-cache` 通过：现有目录 15 项，首次两档图片共 30 次请求，PNG 负载 77,058 字节；未变化的重连图片请求 0 次、PNG 负载 0 字节；生产 Controller 复用缓存时图片写入 0 次。这里统计的是 PNG 负载，不是包含协议与无线链路开销的总传输字节数。 |
+| 设备部署 | 使用现有可回滚开发部署流程，最终服务 active、移动接口可用；部署的移动控制、小图缓存及功能时间文件摘要与本地一致，恢复副本保留。未修改设备 `VERSION`，未导出 OTA/IMG。 |
+| App 交付 | `:androidApp:assembleDebug`、`:androidApp:assembleDebugAndroidTest` 成功；仅 debug 签名。登记手机覆盖安装后的 APK 摘要与交付包一致：`c3ae5ab3caa252f60c715d6f8ecf177767c1e7bc3ea12652b688efe5a3fc3c07`。 |
+
+## 首次失败、修复及复测
+
+- 首次真实 BLE 测试在一条用户动画的 `library.preview` 返回 `BAD_REQUEST`。该动画首帧使用 `path` 指向持久图片，而旧演示动画使用内嵌 `image`；预览/完整图提取现均识别并验证两种形式。控制测试和真实 BLE 全库两档读取复测通过。不能把首次失败写成网络故障。
+- 既有 AVD 名称曾指向已不存在的磁盘目录。保留旧配置，使用已登记的 SDK 镜像新建专用 AVD 后完成上述独立模拟器场景；未清空或覆盖旧 AVD。
+- 一次本地调用只准备了 instrumentation APK，缺少产品 APK；在同一隔离工程补构建产品 APK 后运行成功。运行真机场景前应同时确认两个 APK 都存在。
+
+可复用方法已更新到 [测试流程](../../如何安卓测试/README.md) 和 [排障指南](../../如何安卓测试/常见问题与排障.md)。本归档不保存凭据、真实设备标识、开发机绝对路径或无线数据内容。
+
+## 边界
+
+真实 BLE 结果证明设备上全部现存 15 项的两档接口可读取，且未变化重连没有再次下载；首次加载的 App 逐帧呈现顺序由 JVM 和模拟器验证，不把测试探针的请求顺序冒充真实界面目视结果。没有执行长时间前后台循环、跨 SSID、第二台手机、旧 Android 系统或完整无线链路计量；本轮变更不要求这些专项。没有发现复测后仍未解决的本轮产品故障。
@@ -0,0 +1,47 @@
+# 2026-09-29 Android 按影响选测改造
+
+## 本轮范围和选择理由
+
+改变测试基础设施、场景调度、假数据 UI 环境及协作规则。产品源码、设备部署、协议与版本不变；未导出或发布 APK。测试构建使用既有 debug 签名；源摘要及测试 APK 摘要见 manifest.json，APK 仅为临时验证产物。
+
+本轮新增模拟器框架，因此首次验证所有六个基础场景，并仅对 layout 扩展三组配置。真机只选 connection（验证真实适配器/握手调度）和 navigation（验证 root 输入及权限恢复）。不把框架首次覆盖扩展为以后每轮全量要求。
+
+## 结果
+
+| 验证 | 实际结果 |
+|---|---|
+| sharedCore:jvmTest | 15 个测试，0 failures / errors |
+| Android 产品、真机 instrumentation、独立 uiTest 构建 | 通过；隔离工程使用原有 Gradle 9.5.0 / AGP 9.3.1 / Kotlin 2.4.20 / Compose 1.12.1 |
+| 宿主调度、预览、失败传播、权限/布局恢复 | 9 个 unittest 通过 |
+| 原登记门禁回归 | 8 个 unittest 通过 |
+| 模拟器 API 35 baseline | connection、status、content、settings、navigation、layout 均通过 |
+| 模拟器 layout 配置 | narrow（约340dp）、large-font（1.3）、landscape 均通过 |
+| 模拟器恢复 | 所有运行的字体、方向、密度恢复回读通过；本轮启动实例已退出 |
+| 真机 android-test-a / connection | 加密握手、断开、重新扫描重连通过，instrumentation 16.476 秒；未执行数据读取/切网/轮询/后台专项 |
+| 真机 android-test-a / navigation | 初次 8.19 秒通过；清理范围调整后 8.898 秒通过；独立导航不连接板端，权限恢复和辅助脚本清理通过 |
+| 产品 APK 隔离检查 | dex 不含 FixtureActivity / FixturePlatform / IsolatedUiTest |
+| Git diff 空白检查、Python AST | 通过 |
+
+模拟器逐项结果见三个 JSON。首轮 connection/status 已通过，不因后续内容夹具修复重复运行；后续四项单独重测及补测通过。JSON 中 not_selected 仅描述单次运行，不能误读为整轮没测。
+
+最终 Kotlin 调整仅减少 connection-entry 的无关菜单操作、减少 controller-background 的内容加载，并整理缩进；已重新编译。真实验证证明 connection/navigation 的执行路径；其它新拆分专项只有编译/调度证据，未声称均已真机通过。
+
+## 本轮失败与修复
+
+- 初次 uiTest 配置出现 com.android.test 重复插件版本，以及不存在的 compose.uiTestJUnit4 accessor：复用 AGP classpath 并使用锁定的显式 Compose 测试依赖后构建通过。
+- 系统 Python 缺少 Paramiko：未进入远端测试；改用项目已有本机测试 venv 后真实连接通过，没有为设备端添加依赖。
+- 新 AVD 独立镜像缺包登记且 SDK 根解析不一致：补齐官方包元数据/许可证并正确指定工具对应 SDK 根、复用原 Emulator 后成功；未覆盖现有软件。
+- 模拟器首轮 content 因假条目漏 revision 而失败；补齐真实契约字段后该场景通过。首次失败保留于 ui-baseline-1.json。
+- 最后安装返回值检查修改出现 Python 缩进错误，AST/宿主测试发现；修正后 AST 和全部 9 项宿主测试通过，未在错误状态下运行设备。
+
+可复用经验更新在 [常见问题与排障](../../如何安卓测试/常见问题与排障.md) 第13节，规则和命令更新在 [按影响选测](../../如何安卓测试/按影响选测.md)。
+
+## 按影响跳过与验证边界
+
+本轮未执行实际切网、蓝牙开关、昵称/记忆写入、后台长等待、长轮询、双手机、性能和 systemd 停启；未部署核桃派、切换屏幕内容、启动摄像头或截图。驱动/实屏视觉不适用。
+
+上述真机拆分专项保留为必要时的执行入口，当前实际设备结果仍为未验证，不能用宿主调度通过替代。独立模拟 UI 不证明真实射频、密码错误网络激活、Android 8–11 定位权限、MIUI 后台策略或视觉动画质量；相关修改须补对应证据。
+
+没有发现本轮新增的未解决产品问题；现有构建提示 sharedUi commonTest 未接入 compilation 仍属于既有边界，本轮 UI 实测在独立 uiTest 内完成。
+
+仓库卫生检查通过（624 个 Git 候选文件）。自动审批拒绝临时隔离构建目录删除，目录保留于仓库外受保护临时目录，未尝试其他删除途径。后续构建不依赖它；可复用 SDK、系统镜像和 AVD 保留供按需测试。
@@ -0,0 +1,47 @@
+{
+  "app_version": "0.2.1",
+  "versionCode": 4,
+  "protocol": "1.0 unchanged",
+  "device_version": "not queried: no device deployment or contract change",
+  "apk_sha256": {
+    "androidApp-debug.apk": "75badab341484feea4a95ef697538ad5a879700cfe07850049c5cbbb9fc2094c",
+    "androidApp-debug-androidTest.apk": "3fa608647f8d27146d25f03af8c9bed1b830c8ccf7b09595eae6ebc45e41308d",
+    "uiTest-debug.apk": "20f5ac32fe1bbce70bbcf44e1673fb3c6d5d71f58d3effcbe94434f919fdb109"
+  },
+  "source_sha256": {
+    "androidApp/build.gradle.kts": "7bfbd5d27819700243b7ab1e318eec91024dc170059a92d587400608ec8a59b5",
+    "androidApp/src/androidTest/kotlin/org/qimiaoscreen/controller/AppLifecycleTest.kt": "7b75279ea8bba61fd9a35848339f765e931abb2748dcb2ab08f37f85afd21084",
+    "androidApp/src/androidTest/kotlin/org/qimiaoscreen/controller/BleIntegrationTest.kt": "f286cf70cd00b7e872371f0fbc55f6be46e52602ef6890e974aca1c32eb006fa",
+    "androidApp/src/androidTest/kotlin/org/qimiaoscreen/controller/LayoutTest.kt": "56e99aa9fd54b39fa7bba0efbd24e875afe0e20827deacd654f999f065c83b12",
+    "androidApp/src/androidTest/kotlin/org/qimiaoscreen/controller/WifiSwitchTest.kt": "5ce335ff84fee01230733971964fefde3fcc6103172d3c40fee64f50838b7bcf",
+    "androidApp/src/main/AndroidManifest.xml": "186ed22b19731ea5bf3567e40d6487b95f1bced3dd2fce605de6557cb7c5763e",
+    "androidApp/src/main/kotlin/org/qimiaoscreen/controller/AndroidBle.kt": "a1af9d6593c3be1af0f2a39a3869eae2e1bbbb1dab8b775e06da5dcaa739e9ff",
+    "androidApp/src/main/kotlin/org/qimiaoscreen/controller/MainActivity.kt": "7bece662b79093a19fcdf34ad344cf42a57b60291f0536823395ae06663f4f23",
+    "build.gradle.kts": "feb3b6e64b846f0408cc40e95ae4b632ce9288a56bd6151bc3bbcc46f0549b49",
+    "gradle/libs.versions.toml": "ed393bb2b4d81a162f6b3d21968eeca113e23c2f5d5d22c3be9d104bc592a633",
+    "gradle/wrapper/gradle-wrapper.jar": "497c8c2a7e5031f6aa847f88104aa80a93532ec32ee17bdb8d1d2f67a194a9c7",
+    "gradle/wrapper/gradle-wrapper.properties": "2cb0f9ddf992a26fc4947c91019136bff5e1ccfbf93bd905402b1abf69d15bc5",
+    "gradle.properties": "e7d684b7795fd04ab2e7e96038fa2bf4f9fd633578aa3bb2f5fe367b4f5ec159",
+    "gradlew": "ab5c0cad16305af2e619c159c1f58dd68d07fab9c11e36701e109c0277407f7a",
+    "gradlew.bat": "475c4f08cd57cf2faa819e7f36d72aa93f0ad646ea23a8f7fa3ef54dee1cbc52",
+    "README.md": "7232ebbac0899152e312429fecaf6b3e14b31265b0c50a95c99a6213aa04b2cd",
+    "settings.gradle.kts": "3a1adf811d65cfd2ce28bfeb711990511a29094b8a5b5378f2860c86c9fe83e2",
+    "sharedCore/build.gradle.kts": "9a420e39e3c655f676572d4486e415dbc8b4fd45904db6ad7b64d7fcd71f084b",
+    "sharedCore/src/commonMain/kotlin/org/qimiaoscreen/core/Controller.kt": "48e7bd52250d541088ca2756a8a1dbd37aeedab1ffc03338c9bb7c6ed9d39d7d",
+    "sharedCore/src/commonMain/kotlin/org/qimiaoscreen/core/DeviceLink.kt": "870345382351bbf6d37f4332c0fab099cb47b7b703428a98567a0086c3316be6",
+    "sharedCore/src/commonMain/kotlin/org/qimiaoscreen/core/Protocol.kt": "99264aff225076ef1b423801b9bba8797e0e06a9e759339bc52e896620e4b694",
+    "sharedCore/src/commonMain/kotlin/org/qimiaoscreen/core/SecureChannel.kt": "bde40388bb74c9d47a4e099a14a0baeca3b6bda1539023dbd7dca831c6f24039",
+    "sharedCore/src/commonTest/kotlin/org/qimiaoscreen/core/ControllerRecoveryTest.kt": "9cfd5291d5442ba79802e4193124bc2f22f05cd9a577001d33913d56b140a4a6",
+    "sharedCore/src/commonTest/kotlin/org/qimiaoscreen/core/ProtocolTest.kt": "5d26d3a50c5887d72dc91b2081273fbe4a5a968f01451ef75ab78903d5d42217",
+    "sharedCore/src/javaCryptoMain/kotlin/org/qimiaoscreen/core/JavaSecureChannel.kt": "554d663ceb6ec1be095b31e9ff9549af3ecd02f975059c22ce566c87225b05eb",
+    "sharedCore/src/jvmTest/kotlin/org/qimiaoscreen/core/CryptoInteropTest.kt": "2ddb06c4476952a69bf01c0a3a7164625ae8c0bfe9194349450a2e254888d4b3",
+    "sharedCore/src/jvmTest/kotlin/org/qimiaoscreen/core/RpcTimeoutTest.kt": "fca298fb2266ee7e68e6df76d837f7f191e0046aa5ba321a304c4b4369e064a6",
+    "sharedCore/src/jvmTest/resources/protocol-v1.json": "6280953b95a3f5d1ae531d7feaa6a62848ffa3e438e58308d2a27f04723803dc",
+    "sharedUi/build.gradle.kts": "d469b330d248647e6e93f98d69eb46730adab329ebaf71cbfd896d5426fd0ff1",
+    "sharedUi/src/commonMain/kotlin/org/qimiaoscreen/ui/ControllerApp.kt": "884e61008e49fd3f1c62969cbe38a798f896734fc70f5219b4e00bcb34bfe9a3",
+    "uiTest/build.gradle.kts": "958d9d5509c9b0fd3076f0d22a4544b66e11a4ba47e728107b8ea357cdaffaf3",
+    "uiTest/src/main/AndroidManifest.xml": "ef50ab1e26f0caaadd7997799dd47d510cb7b4042b421ebe5354f4d2d42708dc",
+    "uiTest/src/main/kotlin/org/qimiaoscreen/uitest/FixtureActivity.kt": "86b3d340d1219a4644573a20d78a4f31ac1efbe20df8c16f291eef18507ded41",
+    "uiTest/src/main/kotlin/org/qimiaoscreen/uitest/IsolatedUiTest.kt": "149bf7e3b024206cbf836da8ec113f1c992ae5be0b066f090ca962f808f47188"
+  }
+}
@@ -0,0 +1,37 @@
+{
+  "tests": [
+    {
+      "scenario": "connection",
+      "configuration": "baseline",
+      "result": "passed"
+    },
+    {
+      "scenario": "status",
+      "configuration": "baseline",
+      "result": "passed"
+    },
+    {
+      "scenario": "content",
+      "configuration": "baseline",
+      "result": "failed"
+    },
+    {
+      "scenario": "settings",
+      "configuration": "baseline",
+      "result": "not run"
+    },
+    {
+      "scenario": "navigation",
+      "configuration": "baseline",
+      "result": "not run"
+    },
+    {
+      "scenario": "layout",
+      "configuration": "baseline",
+      "result": "not run"
+    }
+  ],
+  "failure": "Selected Compose scenario failed",
+  "cleanup_errors": [],
+  "not_selected": []
+}
@@ -0,0 +1,30 @@
+{
+  "tests": [
+    {
+      "scenario": "content",
+      "configuration": "baseline",
+      "result": "passed"
+    },
+    {
+      "scenario": "settings",
+      "configuration": "baseline",
+      "result": "passed"
+    },
+    {
+      "scenario": "navigation",
+      "configuration": "baseline",
+      "result": "passed"
+    },
+    {
+      "scenario": "layout",
+      "configuration": "baseline",
+      "result": "passed"
+    }
+  ],
+  "failure": null,
+  "cleanup_errors": [],
+  "not_selected": [
+    "connection",
+    "status"
+  ]
+}
@@ -0,0 +1,28 @@
+{
+  "tests": [
+    {
+      "scenario": "layout",
+      "configuration": "narrow",
+      "result": "passed"
+    },
+    {
+      "scenario": "layout",
+      "configuration": "large-font",
+      "result": "passed"
+    },
+    {
+      "scenario": "layout",
+      "configuration": "landscape",
+      "result": "passed"
+    }
+  ],
+  "failure": null,
+  "cleanup_errors": [],
+  "not_selected": [
+    "connection",
+    "status",
+    "content",
+    "settings",
+    "navigation"
+  ]
+}
@@ -1,5 +1,9 @@
 # 当前实施状态

+更新时间：2026-09-29。当前 App 为 **0.2.2 / versionCode 5**，设备协议 1.1 的“显示内容”两档图片与跨重连缓存已部署。交付包见 `../构建与发布/交付包/0.2.2-5/`，本轮选测、实测请求量、失败修复与未验证边界见 [内容缓存验收](2026-09-29_内容缓存/README.md)。登记手机上的最终 APK 与交付包摘要一致；核桃派服务正常，设备 `VERSION` 仍为 1.1.3，功能时间为 `2026-09-29T22:15+08:00`。本轮只做 debug 签名，没有导出 OTA/IMG。
+
+以下为历史验收记录，不将历史通过项自动归为本轮重测：
+
 更新时间：2026-09-27。当前App为 **0.2.1 / versionCode 4**，顶栏循环、扫描条目断开／连接保留、两页预览居中已实现。交付包 `../构建与发布/交付包/0.2.1-4/`；本轮证据及未验证边界见 [界面细节优化验收](2026-09-27_界面细节优化/README.md)。JVM15项、root三组布局、实际Activity和BLE只读回归通过，最终安装摘要一致；早期测试失败与修正保留。测试流程和排障第12节已更新。设备协议、服务和驱动不变。

 以下为历史验收记录，不将历史通过项自动归为本轮重测：