cmautobuy/docs/task/26-启动时恢复已保存的-android-设备.md

26 启动时恢复已保存的 Android 设备

• 类型：缺陷修复
• 父级大工单：#1
• 所属 MVP / 版本：#2 / MVP
• 状态：已完成
• 日期：2026-08-07
• Gitea 工单：#26

背景与目标

Android 设备保存到 SQLite 后，关闭并重新启动客户端，设备表仍然为空。原因是原启动流程只读取已保存的设备号并显示提示，没有重新查询 ADB 设备。目标是启动时自动恢复已保存设备，并在设备在线时重新显示和勾选。

最终方案

• 没有保存设备号时，不自动执行 ADB 操作。
• 保存的是 Wi-Fi 地址时，在后台先执行 adb connect IP:端口，再刷新设备列表。
• 保存的是 USB 设备号时，只在后台刷新设备列表。
• 已保存设备在线时，自动显示并勾选该设备。
• 恢复失败时保留 SQLite 中的设备号，状态区显示原因，用户可以点击“搜索”重试。
• 复用原有设备搜索 Worker、重复提交保护和页面关闭保护，ADB 命令不阻塞 Qt 主线程。
• 不修改数据库结构、Admin 接口、PDD 自动化和第三方依赖。

本任务没有改变页面布局。按照 windows-ui-ux 的桌面长任务规则，使用后台 Worker 和原状态区反馈，因此不需要制作 HTML 原型。

改了哪些

• client/src/android_device_service.py：增加保存设备恢复入口；区分 Wi-Fi 重连和 USB 刷新。
• client/src/settings_ui_event.py：页面初始化后异步恢复设备，补充成功和失败状态。
• client/test/test_android_device_service.py：覆盖 Wi-Fi、USB 两种恢复命令流程。
• client/test/test_settings_ui_event.py：覆盖无保存配置、自动恢复、失败保留、界面响应和关闭安全。

验收结果

验收标准	结果
无已保存设备时不自动查询 ADB	通过
已保存 Wi-Fi 设备时先重连再刷新	通过
已保存 USB 设备时只刷新列表	通过
在线设备自动显示并勾选	通过
恢复过程不阻塞 Qt 主线程	通过
恢复失败保留已保存配置并可手工重试	通过
页面关闭后忽略迟到结果	通过
不修改数据库、Admin、PDD 和依赖	通过
全量测试、语法检查和差异检查	通过

测试

• Client 全量 92 项自动化测试通过。
• Python 语法检查和 git diff --check 通过。
• 真机启动恢复通过：自动连接并勾选 192.168.0.173:5555，识别型号 PKG110、Android 16，状态为 device。
• 用户已完成客户端重启恢复验收。
• 离屏环境会输出已有的 PyQt5 字体目录缺失提示，不影响恢复结果。
• 没验证到的部分：尚未验证打包后的 exe、设备长期离线后恢复、Narrator、高对比度和 200% 缩放。

相关提交

• dc9b000 fix: 启动时恢复已保存的 Android 设备 (#26)