docs: 归档任务 #66

docs/task/66-Wi-Fi恢复失败后继续搜索设备.md

@@ -0,0 +1,58 @@
+# 66 修复旧 Wi-Fi 设备恢复失败时无法搜索 USB 设备
+
+- 类型：缺陷
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 Client 可运行任务闭环（MVP）
+- 状态：已完成，待用户验收
+- 日期：2026-08-09
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/66
+
+## 背景与目标
+
+Client 保存了不可连接的旧 Wi-Fi ADB 地址时，点击“搜索”会在恢复旧设备失败后
+直接结束，导致 `adb devices -l` 已经识别的 USB 设备也无法显示。本任务让局部
+恢复失败不再中断普通设备搜索。
+
+## 最终方案
+
+- 后台 Worker 仍先尝试恢复已保存设备。
+- 恢复失败时保存警告文字，并继续调用普通设备搜索。
+- 搜索成功结果同时携带实际设备列表和可选恢复警告。
+- 主线程先刷新实际设备表格，再提示旧设备恢复失败、配置已保留。
+- 只有普通设备搜索也失败时才显示“搜索失败”并保留旧表格。
+- 不自动删除或改写已保存设备，不改变保存、删除和 USB 转 Wi-Fi 流程。
+
+## 改了哪些
+
+- `client/src/android_device_service.py`：增加包含设备列表和恢复警告的简单结果对象。
+- `client/src/settings_ui_event.py`：恢复失败后继续搜索，并区分警告与整体失败。
+- `client/test/test_settings_ui_event.py`：补充恢复失败后的 USB、空结果和整体失败测试。
+- `docs/client/05-ui-specification.md`：记录设备搜索的容错与反馈规则。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 已保存 Wi-Fi 在线时正常恢复并自动勾选 | 通过 |
+| 旧 Wi-Fi 离线但 USB 在线时仍显示 USB | 通过 |
+| 旧 Wi-Fi 离线且无其他设备时显示空表和恢复警告 | 通过 |
+| 普通设备枚举失败时保留旧表格并显示搜索失败 | 通过 |
+| ADB 操作继续在工作线程执行 | 通过 |
+| 已保存配置不被自动修改或删除 | 通过 |
+
+## 测试
+
+- 执行的命令：
+  - `C:/Python310/python.exe -m unittest discover -s test -p test_settings_ui_event.py -v`
+  - `C:/Python310/python.exe -m unittest discover -s test -v`
+  - `C:/Python310/python.exe -m py_compile src/android_device_service.py src/settings_ui_event.py`
+  - 设置 `QT_QPA_PLATFORM=offscreen` 后创建并关闭 `MainWindow`
+  - 使用当前保存的旧 Wi-Fi 地址运行 `AndroidDeviceSearchWorker`，观察恢复警告和设备结果
+- 结果：设置页 37 项测试通过；Client 全量 183 项测试通过；语法检查通过；
+  离屏冒烟输出 `OK`；旧 Wi-Fi 恢复超时后仍返回 USB 设备 `30167b23`。
+- **没验证到的部分**：尚未由用户在可见 Client 界面点击“搜索”完成最终交互验收；
+  没有测试可正常连接的真实 Wi-Fi 手机，仅由自动化测试覆盖该分支。
+
+## 相关提交
+
+- `ff8cdd7` 修复 Wi-Fi 恢复失败后继续搜索设备