docs: 归档任务 #44

docs/task/44-优化PDD颜色采集等待时间.md

@@ -0,0 +1,70 @@
+# 44 优化 PDD 颜色采集等待时间
+
+- 类型：重构
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / MVP
+- 状态：已实现，待验收
+- 日期：2026-08-09
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/44
+
+## 背景与目标
+
+颜色采集原来每次点击后固定等待 0.2 秒并最多检查 8 次，水平滑动后还会固定
+等待 0.35 秒。颜色较多或点击未生效时，这些等待会不断累积。本任务改用有总
+超时的短间隔状态检查，在保持颜色顺序和价格稳定判断的前提下减少无效等待。
+
+## 最终方案
+
+- 点击颜色后立即读取控件树，不再先固定等待。
+- 正常价格仍要求连续两次读取结果相同；两次读取之间默认等待 0.1 秒。
+- 选择确认和价格稳定分别计时：默认最多等待 0.6 秒确认选中，确认后最多等待
+  1.2 秒取得稳定价格。目标颜色全程只点击一次。
+- 同时使用单调时钟和有限检查次数，生产环境按实际时间停止，测试注入空等待时
+  也不会形成死循环。
+- 水平滑动后默认等待 0.1 秒并读取控件树；如果视口仍未改变，只补等和补读一次。
+- 滑动后的控件树传给下一轮继续使用，减少一次重复的 `dump_hierarchy()`。
+- 四个等待值集中为 `PddCollectService` 构造参数，并拒绝小于或等于零的配置。
+- 没有修改颜色蛇形顺序、尺码采集、缺价继续提交、数据库和 Admin 接口。
+
+实际实现与建单方案一致。长期文档没有记录具体秒数，因为这些是可调的内部实现
+参数，不属于稳定业务契约。
+
+## 改了哪些
+
+- `client/src/pdd_collect_service.py`：增加颜色等待参数、颜色选择与价格状态轮询、
+  水平滑动延迟更新检查和控件树复用。
+- `client/test/test_pdd_collect_service.py`：增加虚拟时钟，以及立即稳定、选择超时、
+  价格超时和滑动延迟一拍四种测试。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 点击后立即检查，连续两次相同价格即结束 | 通过 |
+| 点击未生效时按选择确认超时返回空价格且只点击一次 | 通过 |
+| 已选中但没有价格时按价格稳定超时返回空价格 | 通过 |
+| 水平滑动固定等待缩短，并能处理一次延迟更新 | 通过 |
+| 保持蛇形顺序、尺码采集和缺价继续提交 | 通过 |
+| 等待参数集中且非法值会被拒绝 | 通过 |
+| PDD 采集专项和 Client 全量测试通过 | 通过 |
+
+## 测试
+
+- 执行的命令：
+
+  ```powershell
+  cd client
+  C:/Python310/python.exe -m py_compile src/pdd_collect_service.py test/test_pdd_collect_service.py
+  C:/Python310/python.exe -m unittest discover -s test -p test_pdd_collect_service.py
+  C:/Python310/python.exe -m unittest discover -s test -p "test_*.py"
+  ```
+
+- 结果：语法检查通过；PDD 采集专项 31 项通过；Client 全量 172 项通过；没有
+  新增依赖。全量测试中的 Qt 字体目录和离屏插件提示是现有环境警告，不影响结果。
+- **没验证到的部分**：未连接真机比较优化前后的完整颜色遍历耗时，也未验证网络
+  较慢时默认 0.6/1.2 秒是否需要回调；没有执行采购或真实下单。
+
+## 相关提交
+
+- `ed72e62` 优化颜色采集等待时间
+- `7b104e3` 覆盖颜色等待参数校验