From 2a3224b86df34b23f4228b741d47211a69043a60 Mon Sep 17 00:00:00 2001 From: chengma Date: Tue, 11 Aug 2026 12:01:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#149?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/149-内置并统一使用项目ADB.md | 68 ++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/task/149-内置并统一使用项目ADB.md diff --git a/docs/task/149-内置并统一使用项目ADB.md b/docs/task/149-内置并统一使用项目ADB.md new file mode 100644 index 0000000..ce83df5 --- /dev/null +++ b/docs/task/149-内置并统一使用项目ADB.md @@ -0,0 +1,68 @@ +# 149 Client：内置指定 ADB 并统一运行路径和缺失提示 + +- 类型：需求 +- 父级大工单：#1 +- 所属 MVP / 版本：#2 / Client 可运行任务闭环 +- 状态：已完成，待用户验收 +- 日期：2026-08-11 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/149 + +## 背景与目标 + +Client 原来直接执行系统 `Path` 中的 `adb`，开发机和发布电脑可能使用不同版本或找不到命令。本任务把用户指定的 ADB 和两个配套 DLL 纳入项目，后续直接 ADB 与 uiautomator2 都使用同一项目文件；文件缺失时中断设备操作并弹窗提示。 + +## 最终方案 + +- 从 `D:\Portable\adb` 复制 `adb.exe`、`AdbWinApi.dll`、`AdbWinUsbApi.dll` 到 `client/vendor/android-platform-tools/windows/`，记录版本 1.0.32 和三个 SHA-256。 +- 增加 `adb_runtime.py`，通过 `app_dir()` 返回源码或 PyInstaller 资源目录中的绝对路径，统一检查三个文件。 +- 直接 subprocess ADB 命令全部使用绝对路径；设置 `ADBUTILS_ADB_PATH`，强制 adbutils/uiautomator2 使用同一文件，不回退系统 `Path`。 +- 启动时发现文件缺失，在主窗口中央显示只有明显“知道了”按钮的中文弹窗；设置页禁用依赖 ADB 的设备命令，不自动恢复已保存设备。 +- 打包脚本显式收集并逐个验证三个文件；诊断工具也改用统一路径。 + +## 改了哪些 + +- `client/vendor/android-platform-tools/windows/`：内置 ADB、DLL 和版本哈希说明。 +- `client/src/adb_runtime.py`、`client/src/db.py`：统一只读资源路径与完整性检查。 +- `client/src/android_device_service.py`：全部命令改用项目 ADB 绝对路径。 +- `client/src/pdd_device_service.py`：uiautomator2 连接前固定 adbutils 的 ADB 路径。 +- `client/src/settings_ui_event.py`、`client/src/ui_main.py`：缺失时禁用设备命令并显示启动弹窗。 +- `client/packaging/build.ps1`：收集并检查三个文件。 +- `client/tools/`、`client/test/`：统一诊断路径并增加回归测试。 +- `docs/client/`：更新上手、发布结构和界面规则。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 项目只复制三个必要 ADB 运行文件 | 通过 | +| 生产 ADB 子进程使用项目绝对路径 | 通过 | +| 清空 Path 后仍解析项目 ADB | 通过 | +| adbutils/uiautomator2 固定使用同一项目 ADB | 通过 | +| 打包脚本收集并检查 ADB 和两个 DLL | 通过 | +| 实际发布包包含三个同哈希文件 | 通过 | +| 文件缺失时弹窗并禁用设备命令 | 通过（自动化测试） | +| 缺失时不回退系统 Path | 通过 | +| USB/Wi-Fi 真机操作 | 未验证 | + +## 测试 + +- 执行的命令： + - `C:/Python310/python.exe -m py_compile src/adb_runtime.py src/db.py src/android_device_service.py src/pdd_device_service.py src/settings_ui_event.py src/ui_main.py tools/measure_goods_open.py tools/test_pdd_home_deeplink.py` + - `C:/Python310/python.exe -m unittest discover -s test -p "test_adb_runtime.py"` + - `C:/Python310/python.exe -m unittest discover -s test -p "test_android_device_service.py"` + - `C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_device_service.py"` + - `C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_home_deeplink.py"` + - `C:/Python310/python.exe -m unittest discover -s test -p "test_packaging.py"` + - `$env:QT_QPA_PLATFORM='offscreen'; C:/Python310/python.exe -m unittest discover -s test -p "test_settings_ui_event.py"; C:/Python310/python.exe -m unittest discover -s test -p "test_pdd_ui_event.py"` + - 清空测试进程 `Path` 后调用 `configure_bundled_adb_environment()` 并核对 `adbutils.adb_path()`。 + - `powershell -ExecutionPolicy Bypass -File packaging/build.ps1 -SkipInstall` +- 结果：相关测试共 144 项全部通过，语法检查和 0.1.0 实际打包通过；发布目录中三个文件哈希与来源一致。PyInstaller 输出已有的 uiautomator2 扩展和 `sip` 收集警告，但构建成功。 +- **没验证到的部分**：没有运行项目 ADB 的 `devices`、USB 转 Wi-Fi 或 uiautomator2 真机连接，避免重启当前 ADB Server 后让已连接的 Wi-Fi 设备临时掉线；没有人工删除打包文件观察真实弹窗外观。 + +## 遗留问题 + +- 用户指定 ADB 为较旧的 1.0.32。若新 Android 设备出现兼容问题，应整体升级三个文件并重新验证，不能临时回退系统 `Path`。 + +## 相关提交 + +- `8f2037d` feat: 内置并统一使用项目 ADB (#149)