chengma/cmbuyer
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(client): add T-101 device baseline

Browse Source
This commit is contained in:
QiuSW
2026-08-03 19:28:39 +08:00
parent f3294633c2
commit de8187eb5b
12 changed files with 1021 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/03-tech-stack.md
+30
View File
@@ -72,6 +72,36 @@
| 测试 | `go test ./...` | `.\.venv\Scripts\python.exe -m unittest discover -s tests -t .` |
| 静态检查 | `go vet ./...` | `.\.venv\Scripts\python.exe -m compileall -q src tests scripts` |
### T-101 设备基线取证（代码已完成，等待人工真机验收）
`client/scripts/capture_device_baseline.py` 只允许对**手工明确填写**的 ADB serial 做连接前核验、
设备型号 / Android / 拼多多版本读取、截图和 `dump_hierarchy(compressed=False)`。它不打开商品、
不读取页面判据，也不执行采购、下单或付款动作。多个在线通道必须完成 `getprop` 物理身份比对：
同一手机 USB + WiFi 同时在线，或任一在线通道的身份读取失败，都会 fail closed，不能随机继续。
人工验收前，先由人把手机切换到不含收货地址、手机号、支付信息或其他无关隐私的安全页面，再在
`adb devices -l` 中**手工复制**一个在线 serial；USB 和 WiFi 分别验收，且每次只保留一个通道在线。
WiFi 通道必须由人先行建立；脚本禁止 `adb connect`、`adb disconnect` 或自动重连。以下命令中的尖括号
必须替换为该次人工确认的实际 serial，不能省略或改成自动选择：
```powershell
# 仓库根目录；先手工确认设备状态，命令本身只读 ADB 清单
D:\Portable\adb\adb.exe devices -l
# USB：粘贴该次 devices -l 显示的 USB serial
.\client\.venv\Scripts\python.exe client\scripts\capture_device_baseline.py --serial <USB_SERIAL> --output-dir "$env:LOCALAPPDATA\cmbuyer\artifacts\T-101\usb-baseline" --timeout 10 --adb D:\Portable\adb\adb.exe
# WiFi：由人先建立 WiFi ADB 通道、断开 USB 后，粘贴该次 devices -l 显示的 WiFi serial
.\client\.venv\Scripts\python.exe client\scripts\capture_device_baseline.py --serial <WIFI_SERIAL> --output-dir "$env:LOCALAPPDATA\cmbuyer\artifacts\T-101\wifi-baseline" --timeout 10 --adb D:\Portable\adb\adb.exe
```
成功时输出目录仅包含截图、完整 XML 与不含页面正文的 `manifest.json`（设备元数据、通道、时间、
文件 SHA-256 和 serial 哈希）。`--timeout` 约束 ADB 命令、ADB socket 及 `takeScreenshot` /
`dumpWindowHierarchy(compressed=False, max_depth=50)` 的公开 JSON-RPC 调用；uiautomator2 初始化仍有
上游固定启动上限。XML 仅留在本机明确指定的证据目录；人工必须先在本地检查截图/XML，再只记录路径
和哈希，不得把原始证据提交 Git；之后把设备型号、Android、拼多多版本及 USB/WiFi 结论记录到 T-101，
才能完成该任务。
Windows 的标准入口是仓库根 `./init.ps1`。它要求 Go、两端目录及其哨兵文件存在；已有合规
`client/.venv` 时，所有采购工具检查与 validator 都使用该解释器。只有 venv 不存在时，才从 `py -0p`
枚举的版本中确定性选择最高的 Python 3.11+ 创建它；没有合规版本时明确失败，绝不回退默认 `python`。
docs/04-architecture.md
+1 -1
View File
@@ -386,7 +386,7 @@ PENDING_RETRIAL ─────────────┴─claim→ CLAIMED
| 同一商品两趟结果不一致 | 第二趟价格变了、规格选项变了或商品下架 | 闸门二拦截；一律转人工，不自动放弃也不自动继续 |
| 图搜结果含跨类目商品（V2） | 搜服装出现纸巾 | B 路径只产 goods_id 且限 5 个；后续用 VLM 看截图筛同款 |
| WiFi ADB 稳定性 | 息屏、换网、DHCP 续租会断连 | 超时可配置；断连视为技术失败并保留现场，不重试点击 |
| 同一手机 USB + WiFi 同时在线 | `adb devices` 列出两条，自动选设备会失败 | 设备档案必须显式指定 serial，不允许留空自动选 |
| 同一手机 USB + WiFi 同时在线 | `adb devices` 列出两条，自动选设备会失败 | serial 必填；多在线通道必须读到 `ro.serialno` 或 `ro.boot.serialno` 才能比对。身份一致或任一身份读取失败时都 fail closed，不能以相同 model/product 猜测后继续 |
| 不可逆动作的重试 | 点击「现在买」后超时，无法判断订单是否已创建 | 一律转人工并预留金额额度，**禁止自动重试点击** |
| 双端契约漂移 | 两端独立演进会静默不兼容 | 契约改动必跑完整门禁；[api.md](api.md) 是唯一权威 |
docs/current-state.md
+28 -9
View File
@@ -18,17 +18,18 @@
使用 Python 3.11+ / uiautomator2 / PySide6。
详见 [`03-tech-stack.md`](03-tech-stack.md)
- 生产代码：`admin/` 已有最小 Go 服务、健康检查、核心领域模型、SQLite 迁移与任务状态机；
`client/` 已有 Python 包、PySide6 最小入口、运行目录与日志脱敏策略；尚无真机采购流程
- 测试：采购服务已覆盖健康检查、核心模型、迁移与状态机等离线包级测试；采购工具 6 项离线单元测试
（不连接真机）
`client/` 已有 Python 包、PySide6 最小入口、运行目录与日志脱敏策略，以及显式 serial 的 ADB
连接边界与本地基线取证 CLI；尚无真机采购流程
- 测试：采购服务已覆盖健康检查、核心模型、迁移与状态机等离线包级测试；采购工具 27 项离线单元测试
（全部 mock，不连接真机）
- 数据：SQLite 核心表与迁移已落成；无业务实例数据
- 标准启动路径：Windows PowerShell 运行 `./init.ps1`，Unix shell 运行 `./init.sh`。Windows 入口
优先使用合规的既有 venv；仅在其缺失时才从 Python Launcher 已安装版本中选择最高的 Python 3.11+，
并且不覆盖低版本环境；成功后打印真实启动命令。
- 标准验证路径：`./init.ps1` 已实际跑通 admin 的 mod download / test / vet / build、client 的
editable install / 包导入 / unittest / compileall，以及仓库上下文校验。可单独运行两端命令诊断。
- 当前 blocker：无外部 blocker。T-002、T-003、T-004 已完成；T-101 真机环境盘点已就绪，
但尚未真机验收。桌面 GUI 与真机流程尚未验收。
- 当前 blocker：T-101 等待人工分别完成 USB 与 WiFi 真机验收；这是 Phase 1 后续任务的门禁。
T-002、T-003、T-004 已完成，桌面 GUI 与真机流程尚未验收。
## 当前目录要点
@@ -39,7 +40,7 @@
| `docs/design/` | 已有（6 个原型） | web 登录 / 建单 / 工作台 / 详情，desk 采购执行 / 配置；均已人工确认 |
| `scripts/` | 已有 | 上下文门禁、Vikunja 单向导出与 MCP 启动包装 |
| `admin/` | 已初始化 | Go 1.23+ / gin / SQLite，含核心模型、迁移与状态机；无真机采购执行 |
| `client/` | 已初始化 | Python 3.11+ 包、依赖源、PySide6 最小入口、离线测试与 wheel 元数据检查；无真机或采购流程 |
| `client/` | 已初始化 | Python 3.11+ 包、依赖源、PySide6 最小入口、显式 serial 的设备基线取证、离线测试与 wheel 元数据检查；无采购流程 |
| `init.ps1` / `init.sh` | 已完成 | 统一安装与离线验证入口；PowerShell 优先复用合规 venv，缺失时自动选择最高的 Python 3.11+，Unix 缺工具链明确失败 |
## 任务状态
@@ -50,8 +51,8 @@
源码目录契约）、T-008（Vikunja 任务权威与单向导出）、T-009（MVP 关键路径与并行波次），
以及 T-001（采购服务 Go 骨架）。
- 已完成：T-002（采购工具 Python 骨架）、T-003（双端统一初始化与验证入口）、
T-004（核心数据模型）。T-101（真机环境盘点）已建档并就绪，尚未真机验收，接续推进
T-101 → T-102 → T-103。
T-004（核心数据模型）。T-101（真机环境盘点）已完成离线实现和 mock 测试，仍为 `DOING`，
必须等待人工 USB、WiFi 两通道真机验收后才能完成；接续推进 T-101 → T-102 → T-103。
- T-103 是当前最高优先级和 MVP 生死线。通过前不开发依赖真机可读字段的 Phase 2 生产页面。
- 已确认原型继续只作信息架构依据；原型假数据不调用真实接口、不驱动真机。真机结论改变
可读字段时必须先回修原型与交互清单。
@@ -93,10 +94,28 @@ cd client
```
`client/requirements.txt` 是唯一依赖来源，`client/pyproject.toml` 动态读取它生成 wheel 的
`Requires-Dist`。Python 3.12 已验证 6 项离线测试、编译与 wheel 元数据；完整运行时依赖安装
`Requires-Dist`。Python 3.12 已验证 27 项离线测试、编译与 wheel 元数据；完整运行时依赖安装
（`pip install -e .`）已通过。`init.ps1` 优先使用合规既有 venv，缺失时自动选择最高的 Python 3.11+；
本机现有 venv 实际验证为 Python 3.12。桌面 GUI 与真机流程未作为 T-003 验收执行。
T-101 的人工真机验收命令（先把手机切到不含收货地址、手机号、支付信息或其他无关隐私的安全页面；
必须从 `adb devices -l` 手工复制在线 serial，不能留空或自动选择）：
```powershell
# 仓库根目录；USB 和 WiFi 分开执行，每次只保留一个通道在线
D:\Portable\adb\adb.exe devices -l
.\client\.venv\Scripts\python.exe client\scripts\capture_device_baseline.py --serial <USB_SERIAL> --output-dir "$env:LOCALAPPDATA\cmbuyer\artifacts\T-101\usb-baseline" --timeout 10 --adb D:\Portable\adb\adb.exe
# WiFi 必须由人先建立通道、断开 USB 后再手工粘贴在线 WiFi serial；脚本不自动 connect/reconnect
.\client\.venv\Scripts\python.exe client\scripts\capture_device_baseline.py --serial <WIFI_SERIAL> --output-dir "$env:LOCALAPPDATA\cmbuyer\artifacts\T-101\wifi-baseline" --timeout 10 --adb D:\Portable\adb\adb.exe
```
脚本只读取非敏感设备元数据、拼多多版本、截图和完整 XML；不会打开商品或写页面判据。它对同机双
通道、身份读取失败、offline、unauthorized、超时或 serial 不存在均 fail closed。成功目录的
`manifest.json` 只记录元数据、产物路径和 SHA-256，不记录 XML 页面正文或原始 serial。人工记录
两次验收结果前，T-101 必须保持 `DOING`。`--timeout` 约束 ADB 命令、ADB socket 以及截图/节点树的
公开 JSON-RPC 调用；uiautomator2 初始化仍有上游固定启动上限。截图/XML 只在本地人工检查，执行记录
只写路径和 SHA-256，原始证据不得提交 Git。
## 关键背景
本项目是 `cmroubao`（Go 后端 + Android AccessibilityService）与 `cmpdd`
docs/tasks/T-101.md
+5 -1
View File
@@ -23,7 +23,7 @@ write_paths:
- docs/current-state.md
---
<!-- BEGIN VIKUNJA EXPORT id=21 synced=2026-08-03T10:56:38Z sha256=b9e15dc40c426b90f0a1d4b9c5dc2809d246105cad609343c10f471b44f1e491 -->
<!-- BEGIN VIKUNJA EXPORT id=21 synced=2026-08-03T11:27:34Z sha256=d4d45d10242f66c3c562ddece0f0a45709af7d54286deebc496816c08ed4c2a4 -->
## 问题 / 背景
T-002 已建立采购工具骨架，但本项目还没有对实际 Android 手机、ADB 通道或 uiautomator2 做过取证。后续所有拼多多页面判据都依赖稳定、显式且可审计的设备连接；若复用前序项目结论或自动猜设备，会把错误设备和旧页面事实带入生产流程。
@@ -55,6 +55,10 @@ T-002 已建立采购工具骨架，但本项目还没有对实际 Android 手
### 2026-08-03T10:56:19Z · ila
T-101 已领取，Git 状态将提交为 DOING。只读环境盘点：adb 位于 D:\Portable\adb\adb.exe；当前同时列出 WiFi serial 192.168.0.173:5555 与 USB serial 3B65BD02H7F00000，二者 product/model/device 均为 PKG110/PKG110/OP5D2BL1。该现场必须由实现识别为同机双通道并 fail closed。尚未截图、dump 或操作手机，本记录不是人工真机验收；needs_device 规则继续生效。
### 2026-08-03T11:27:08Z · ila
2026-08-03 离线实现与主审完成：新增显式 serial 的 ADB 边界、USB/WiFi 同机多通道 fail-closed、禁止 uiautomator2 隐式重连的连接器，以及只读基线 CLI（型号、Android、拼多多版本、截图、compressed=false XML、manifest SHA-256）。主 agent 三轮审查后补齐：截图/XML JSON-RPC 可配置超时、adbutils/uiautomator2 类型化超时、完整硬件身份集合比对、非法截图/XML fail-closed、异常脱敏、暂存清理，以及人工安全页面/原始证据不入 Git 的操作要求。独立验证：init.ps1 通过；admin go test/vet/build 通过；client 27 项 mock 单测、compileall、wheel METADATA、validator、bash -n 与 diff check 通过。未连接或操作真机，T-101 继续保持 DOING；等待人分别完成 USB 与 WiFi 取证并记录 manifest 中的设备型号、Android、拼多多版本、路径与 SHA-256。已知边界：ADB/ADB socket/截图与节点树 RPC 超时可配置，uiautomator2 初始化仍受上游固定启动上限约束。
<!-- END VIKUNJA EXPORT -->
## 边界