Improve controller behavior and update project requirements

移动端相关内容/安卓app/如何安卓测试/常见问题与排障.md

@@ -69,3 +69,19 @@ Compose 的禁用语义可能位于父节点，文字节点自身仍 enabled。
 滑动后通过两次间隔400毫秒的实时边界相等检查确认目标停稳（最多5秒），然后仅发送一次 root 点击；不因未看到中间状态而重复点击连接。记录初次连接、连接中扫描、两处预览、条目断开、手动重连等阶段。短暂“连接中”未被观测不代表未发起请求，终态以认证连接和条目状态核验为准。
 
 本轮失败、恢复与最终结果见 `../测试结果归档/2026-09-27_界面细节优化/`；重测通过不证明此前连接未出现的唯一根因。字体、旋转和密度恢复后均回读核验。
+
+## 13. 按影响选测与独立模拟器（2026-09-29）
+
+- 先读 [按影响选测](按影响选测.md)，选中场景后才执行环境门禁。不能因为手机登记/网络不可用而阻塞不依赖它们的 JVM、模拟器或文档检查。需要真机但环境不可用时仍是“未验证”。
+- `--list-scenarios` / `--dry-run` 不导入远端联调依赖、不访问凭据或 ADB。电脑系统 Python 未装 Paramiko 时，优先复用本机测试环境的 `.venv` 并检查 import；不要给核桃派添加主机依赖。
+- com.android.test 插件已由同版本 AGP 放入 classpath 时，uiTest 使用无版本 `id("com.android.test")`；显式重复版本可能导致 unknown version 冲突。uiTest 的 Compose 测试库与现有 Compose Multiplatform 锁定版本一致。
+- 独立 uiTest 使用 self-instrumenting APK 和实际 Controller，不从反射篡改内部状态。fake RPC 必须遵循真实字段契约：内容条目需要 revision，缺失会在 thumbnailKey 中失败。此类夹具错误应修夹具，不弱化产品断言。
+- 真机 navigation 临时撤销扫描/连接权限，防止已有记忆触发自动重连；finally 恢复原权限并回读，不访问板端身份。不将此场景用于权限允许/拒绝的产品验收。
+- AVD 镜像 ZIP 手动解压不等于 SDK 包已登记。单独存放 SDK 时，avdmanager 必须定位同一 SDK 根；镜像 package.xml 保留官方 type-details/版本/许可证，复用已有 Emulator。优先使用 Android Studio SDK Manager 正常安装的包，不能靠反复下载解决根目录不一致。
+- 模拟器测试出现失败，保留场景与配置结果，独立恢复字体、旋转、密度；只重跑受影响/未运行场景。失败不能记成全量通过。标准 Compose 输入仅适用于模拟器，登记真机仍用 root。
+
+## 14. 内容预览在真实动画条目返回 BAD_REQUEST（2026-09-29）
+
+真实用户动画的首帧可能是 `path` 指向持久图片，演示动画则可能是内嵌 `image`。新增 BLE 图片接口时要先检查 `animations.playback_snapshot` 的实际首帧结构，并沿设备既有路径验证与解码规则读取两种形式；不能把 `path` 当作无图或错误参数。空动画仍应按不可播放条目处理。复测须覆盖用户动画和演示动画，并做全库图片只读读取；本轮修正和实测见 [内容缓存验收](../测试结果归档/2026-09-29_内容缓存/README.md)。
+
+模拟器 AVD 名称若存在但启动提示系统目录不存在，先核对该名称的配置指向和镜像登记。保留旧配置，使用已安装镜像新建专用 AVD 再测试；不要因名称存在就反复启动，也不要擅自清空原 AVD。真机 instrumentation 前同时确认产品 APK 与 androidTest APK 已构建，只有测试 APK 时先补产品构建，再运行选中场景。