docs: 归档任务 #27

docs/task/27-修复-wifi-adb-拔线后刷新丢失.md

@@ -0,0 +1,73 @@
+# 27 修复 Wi-Fi ADB 拔线后刷新丢失
+
+- 类型：缺陷
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / MVP
+- 状态：已实现，待验收
+- 日期：2026-08-07
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/27
+
+## 背景与目标
+
+USB 转为 Wi-Fi ADB、勾选 Wi-Fi 并保存后，拔掉 USB 数据线再搜索，设备列表会变空。SQLite 保存正常，直接原因是普通搜索只执行 `adb devices -l`，没有重新连接保存的 Wi-Fi 地址；旧转换流程还可能把 adbd 重启误判成已经拔线。
+
+目标是让转换在插着 USB 时完成，并让搜索自动恢复已保存的 Wi-Fi ADB。
+
+## 最终方案
+
+- USB 转 Wi-Fi 不再等待或判断物理拔线。
+- 插着 USB 依次读取手机 IP、开启 5555、连接 Wi-Fi，并等待 USB、Wi-Fi 两个 ADB transport 稳定。
+- 转换成功后刷新列表、勾选 Wi-Fi，并提示用户先保存再拔 USB；转换本身不写数据库。
+- 普通搜索发现已保存设备是 Wi-Fi 地址时，先执行 `adb connect`，再读取设备列表。
+- ADB 重启或授权握手期间短暂出现 `unauthorized` 时，后台最多等待约 2 秒；持续未授权则提示用户在手机上允许调试，不自动勾选。
+- 失败时保留原表格和 SQLite 配置，允许用户重试。
+- 所有 ADB 命令、等待和重试继续在 `QObject + moveToThread` Worker 中执行，页面关闭后忽略迟到结果。
+- 不修改数据库结构、Admin、PDD 自动化和第三方依赖。
+
+本任务只调整已有命令行为和状态反馈，没有改变页面布局。按照 `windows-ui-ux` 的 Qt 长任务和表格勾选规则，保持后台执行、稳定设备号勾选及非模态状态提示，因此跳过 HTML 原型。
+
+## 改了哪些
+
+- `client/src/android_device_service.py`：简化转换流程，增加 ADB transport 稳定等待和保存 Wi-Fi 重连。
+- `client/src/settings_ui_event.py`：普通搜索自动重连已保存 Wi-Fi，区分启动恢复、手工搜索和未授权状态。
+- `client/test/test_android_device_service.py`：覆盖插线转换、命令顺序、短暂未授权和连接验证。
+- `client/test/test_settings_ui_event.py`：覆盖手工重连、失败保留、未授权提示、双设备显示和关闭安全。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 转换不等待或误判物理拔线 | 通过 |
+| 插线状态完成 Wi-Fi 连接并显示 USB、Wi-Fi | 自动测试及真机通过 |
+| 转换后提示保存，再拔掉 USB | 通过 |
+| 转换不会自动写入设备配置 | 通过 |
+| 已保存 Wi-Fi 时搜索先重连再查询 | 自动测试及真机通过 |
+| 拔掉 USB 后刷新显示并勾选 Wi-Fi | 逻辑与 ADB 断连真机测试通过，待用户物理拔线验收 |
+| 无已保存 Wi-Fi 时不执行额外连接 | 通过 |
+| 重连失败保留配置并提供恢复提示 | 通过 |
+| 短暂未授权会等待，持续未授权有明确提示 | 通过 |
+| 主线程响应、重复点击和关闭安全 | 通过 |
+| 不修改数据库、Admin、PDD 和依赖 | 通过 |
+| 全量测试、语法检查、离屏冒烟和差异检查 | 通过 |
+
+## 测试
+
+- 执行的命令：
+
+```powershell
+# client 目录
+C:/Python310/python.exe -m py_compile src/android_device_service.py src/settings_ui_event.py test/test_android_device_service.py test/test_settings_ui_event.py
+$env:QT_QPA_PLATFORM="offscreen"
+C:/Python310/python.exe -m unittest discover -s test -p "test_*.py"
+```
+
+- 结果：Client 全量 95 项测试通过；语法检查、进入 Qt 事件循环的主窗口启动/退出冒烟及 `git diff --check` 通过。
+- 真机转换：USB `3B65BD02H7F00000` 转换后稳定返回 USB 与 `192.168.0.173:5555`，两者状态均为 `device`。
+- 真机重连：主动断开 `192.168.0.173:5555` 的 ADB 会话后点击搜索，程序自动重连并勾选该设备，识别为 `PKG110 / Android 16 / device`。
+- **没验证到的部分**：无法代替用户物理拔掉 USB 数据线，待可见客户端验收；尚未验证手机重启、IP 改变、切换网络、打包后的 exe、Narrator、高对比度和 200% 缩放。
+
+测试环境仍会输出已有的 PyQt5 字体目录缺失和 SIP API 弃用警告，不影响测试结果。
+
+## 相关提交
+
+- `5750397` `fix: 修复 Wi-Fi ADB 拔线后刷新丢失 (#27)`