From 03f91c24883e592ddc9134c898f0bb97ad353b4d Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Fri, 7 Aug 2026 11:54:05 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?=
 =?UTF-8?q?#21?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/task/21-实现-android-设备搜索.md | 69 +++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 docs/task/21-实现-android-设备搜索.md

diff --git a/docs/task/21-实现-android-设备搜索.md b/docs/task/21-实现-android-设备搜索.md
new file mode 100644
index 0000000..6d32338
--- /dev/null
+++ b/docs/task/21-实现-android-设备搜索.md
@@ -0,0 +1,69 @@
+# 21 实现 Android 设备搜索
+
+- 类型：需求
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / MVP
+- 状态：已实现，待验收
+- 日期：2026-08-07
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/21
+
+## 背景与目标
+
+设置页原有“搜索”按钮只会发出信号，没有执行 ADB 查询。此次补齐实际搜索能力，让用户能够在不阻塞界面的情况下查看电脑当前识别的 USB 和 Wi-Fi Android 设备。
+
+## 最终方案
+
+- 新增独立的 `AndroidDeviceService`，使用标准库执行 `adb devices -l`。
+- 解析设备号、USB/Wi-Fi 连接方式、型号和 ADB 状态；正常设备再查询 Android 版本。
+- 单台设备的属性读取失败时保留该设备，并用 `—` 表示未知属性。
+- 使用 `QObject + moveToThread` 在后台搜索，工作线程不访问 QWidget。
+- 搜索期间禁用设备管理命令；成功、无设备、失败和超时使用页面原有状态区反馈。
+- 搜索失败保留上一次列表；搜索成功按稳定设备号保留仍有效的勾选。
+- 页面关闭时停止后续属性查询、断开界面信号，并等待当前 ADB 命令在有限超时内结束。
+- 没有增加依赖，没有修改数据库、Admin 接口、设备连接和 PDD 自动化逻辑。
+
+该任务是现有设置页的局部交互补全，没有改动布局，因此按 Windows UI/UX 规范跳过 HTML 原型。
+
+## 改了哪些
+
+- `client/src/android_device_service.py`：ADB 命令执行、列表解析、属性补充和可读错误。
+- `client/src/settings_ui_event.py`：搜索 Worker、线程生命周期、状态反馈和重复点击保护。
+- `client/src/settings_ui.py`：注入设备服务，并补充设备状态区无障碍名称。
+- `client/test/test_android_device_service.py`：覆盖 USB/Wi-Fi、属性读取、ADB 缺失、失败和超时。
+- `client/test/test_settings_ui_event.py`：覆盖成功、空列表、失败保留、勾选保持、主线程响应和关闭安全。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 点击搜索会在后台执行 ADB，Qt 主线程保持响应 | 通过 |
+| USB 和 Wi-Fi 设备正确区分 | 通过 |
+| 正常设备显示型号、Android 版本和已连接状态 | 自动测试通过，待可见真机核对 |
+| 离线、未授权设备显示且不可勾选 | 通过 |
+| 无设备时保留占位行并提示 | 通过 |
+| ADB 缺失、失败和超时提供恢复提示 | 通过 |
+| 搜索期间防止重复搜索，完成后恢复按钮 | 通过 |
+| 刷新按设备号保持或清除勾选 | 通过 |
+| 页面关闭后忽略迟到结果 | 通过 |
+| 不增加依赖，不修改数据库和 Admin 接口 | 通过 |
+| 全量测试、语法检查和差异检查 | 通过 |
+
+## 测试
+
+- 执行的命令：
+
+```powershell
+# client 目录
+C:/Python310/python.exe -m py_compile src/android_device_service.py src/settings_ui.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 全量 61 项测试通过；真实 ADB 服务调用曾识别到 1 台 Wi-Fi 设备；设备断开后的真实离屏按钮搜索正确显示无设备状态。
+- **没验证到的部分**：尚未在设备保持连接时，用可见窗口人工核对设备号、型号、Android 版本和状态列；未验证打包后的 exe 查找系统 ADB；Narrator、高对比度和 200% 缩放未做人工检查。
+
+测试环境仍会输出现有 PyQt5 字体目录缺失和 sip API 过时警告，不影响测试结果。
+
+## 相关提交
+
+- `45fde81` `feat: 实现 Android 设备搜索 (#21)`