docs: 归档任务 #256

docs/task/256-client采购尺码候选完整采集.md

@@ -0,0 +1,62 @@
+# 256 Client：采购尺码不匹配时完整采集真机候选
+
+- 类型：需求
+- 父级大工单：#96
+- 所属 MVP / 版本：#253
+- 状态：已完成
+- 日期：2026-08-17
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/256>
+
+## 背景与目标
+
+采购任务已经选中正确颜色，但目标尺码不在页面时，后续规格解析需要一份完整、
+可复核的当前颜色尺码候选。候选采集必须只读，并且不能把页面不完整、点击失败或
+候选不稳定误判成需要远端解析。
+
+## 最终方案
+
+采购 Adapter 复用 `PddCollectService` 已有的第二规格遍历，不另写一套滚动算法。
+采购候选模式要求确认遍历起点和终点；滚动中规格状态改变、页面丢失或达到上限时，
+返回普通采购失败。
+
+只有颜色已经可靠选中、尺码失败原因为 `target_not_visible`，并且完整列表中也不存在
+目标原文或唯一繁简等价文字时，才生成 `PddPurchaseSpecResolutionRequired`。内存快照
+保留规格名称、全部原文、可用状态和页面顺序；可购买项按顺序编号为 `c1`、`c2`，并按
+`spec-resolution-v1` 契约计算 SHA-256。不可购买项不进入待解析候选。
+
+本工单不请求 Admin、不点击解析结果，也不把候选或控件树写入 SQLite、日志或文档。
+
+## 改了哪些
+
+- `client/src/pdd_collect_service.py`：开放严格、只读的第二规格候选遍历入口。
+- `client/src/pdd_purchase_adapter.py`：增加观察项、候选快照和待解析异常对象。
+- `client/src/pdd_u2_purchase_adapter.py`：接入候选采集门禁，并区分待解析与普通失败。
+- `client/test/test_pdd_collect_service.py`：验证公开入口复用原第二规格遍历。
+- `client/test/test_pdd_u2_purchase_adapter.py`：验证触发门禁、可用状态、编号、哈希和失败分流。
+- `docs/client/01-requirements.md`：补充采购尺码候选采集需求。
+- `docs/client/02-architecture.md`：记录复用边界、快照结构和职责分工。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 复用现有第二规格遍历，不复制滚动算法 | 通过 |
+| 保留规格名称、原文、可用状态、页面顺序和稳定候选编号 | 通过 |
+| 快照哈希符合 `spec-resolution-v1` 契约 | 通过 |
+| 仅在颜色已选且目标确实不在完整列表时返回待解析结果 | 通过 |
+| 扫描不完整、目标仍存在和未选颜色均按普通采购失败处理 | 通过 |
+| 不调用 Admin、不点击解析结果、不持久化 XML 或候选 | 通过 |
+
+## 测试
+
+- 执行的命令：`$env:PYTHONPATH='client'; C:/Python310/python.exe -m pytest client/test/test_pdd_u2_purchase_adapter.py client/test/test_pdd_collect_service.py -q`
+- 结果：127 passed。
+- 执行的命令：`$env:PYTHONPATH='client'; C:/Python310/python.exe -m pytest client/test -q`
+- 结果：480 passed，2 failed；失败是工作区版本号已为 `0.1.2`，两个旧测试仍固定期望 `0.1.0`，与本工单无关。
+- 执行的命令：`C:/Python310/python.exe -m py_compile client/src/pdd_purchase_adapter.py client/src/pdd_collect_service.py client/src/pdd_u2_purchase_adapter.py`
+- 结果：通过。
+- **没验证到的部分**：未连接真机执行一次实际长尺码列表遍历；本工单使用模拟控件树和设备行为验证。
+
+## 相关提交
+
+- `58dc902` feat: 完整采集采购尺码候选 (#256)