From b11a586527fd69f2c046ef049a875e63b68255e0 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Mon, 17 Aug 2026 15:21:09 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?=
 =?UTF-8?q?#251?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../251-安全兼容采购规格繁简体唯一匹配.md     | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/task/251-安全兼容采购规格繁简体唯一匹配.md

diff --git a/docs/task/251-安全兼容采购规格繁简体唯一匹配.md b/docs/task/251-安全兼容采购规格繁简体唯一匹配.md
new file mode 100644
index 0000000..b8c0c85
--- /dev/null
+++ b/docs/task/251-安全兼容采购规格繁简体唯一匹配.md
@@ -0,0 +1,73 @@
+# 251 安全兼容采购规格繁简体唯一匹配
+
+- 类型：缺陷
+- 父级大工单：#1
+- 所属 MVP / 版本：#2
+- 状态：已完成，待用户验收
+- 日期：2026-08-17
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/251
+
+## 背景与目标
+
+采购任务 cg44 的目标颜色使用繁体文字，PDD 规格面板显示对应简体文字。
+原选择器只做原文严格匹配，完成横向扫描后仍错误报告找不到目标颜色。
+
+本任务让颜色和尺码支持安全的繁简等价比较，同时保证候选不唯一时停止采购，
+不使用包含关系、编辑距离或其他模糊匹配。
+
+## 最终方案
+
+- 使用 Windows `LCMapStringEx` 生成简体规格比较键，不增加第三方依赖。
+- 比较前执行 Unicode NFKC；原文、Admin payload 和 SQLite 数据保持不变。
+- 原文精确匹配优先；只有繁简规范化候选的安全点击边界唯一时才允许点击。
+- 同一卡片的外层和文字点击区域按包含关系合并，避免误判为两个候选。
+- 多个不同繁简等价候选返回 `target_ambiguous`，不点击任何候选。
+- 点击前完成唯一性检查；点击后允许 PDD 新增“已选”摘要，并继续用最新控件树确认选中状态。
+- 颜色、尺码选择失败在对应性能阶段内抛出，使日志准确记录为 `failed`。
+
+与建单方案一致，没有修改 Admin 接口、数据库、任务状态、地址、价格数量复核、
+不可逆门禁和下单流程。
+
+## 改了哪些
+
+- `client/src/util/select_color_size.py`
+  - 增加繁简规格规范化、精确匹配优先、候选边界合并和歧义拒绝。
+  - 增加尺码选择失败原因。
+- `client/src/pdd_u2_purchase_adapter.py`
+  - 增加颜色、尺码繁简歧义提示。
+  - 修正选择失败阶段的性能日志结果。
+- `client/test/test_select_color_size.py`
+  - 覆盖繁简颜色、繁简尺码和重复候选拒绝。
+- `client/test/test_pdd_u2_purchase_adapter.py`
+  - 覆盖颜色、尺码失败时性能阶段记录为失败。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 繁体颜色唯一匹配 PDD 简体颜色 | 通过 |
+| 繁体尺码唯一匹配 PDD 简体尺码 | 通过 |
+| 原有完全一致规格保持原逻辑 | 通过 |
+| 多个繁简等价候选时不点击并返回歧义 | 通过 |
+| 不使用包含关系或编辑距离猜测规格 | 通过 |
+| 颜色、尺码选择失败计时记录为 `failed` | 通过 |
+| 不修改不可逆门禁、地址和提交逻辑 | 通过 |
+| 专项及 Client 回归 | 专项通过；全量有 2 个既有版本断言失败 |
+
+## 测试
+
+- 执行的命令：
+  - `C:/Python310/python.exe -m py_compile src/util/select_color_size.py src/pdd_u2_purchase_adapter.py`
+  - `C:/Python310/python.exe -m pytest test/test_select_color_size.py test/test_pdd_u2_purchase_adapter.py -q --disable-warnings`
+  - `C:/Python310/python.exe -m pytest test -q --disable-warnings`
+- 结果：
+  - 语法检查通过。
+  - 专项测试 60 项全部通过。
+  - 全量测试 478 项中 476 项通过。
+  - 2 项既有失败均为当前版本 `0.1.2` 与旧测试固定期待 `0.1.0` 不一致，和 #251 无关。
+  - 对当前真机控件树做了只读验证：繁体目标可唯一定位简体颜色卡片，未点击。
+- **没验证到的部分**：未在真机执行选色、选尺码、地址修改、下单或付款；需用户使用新采购任务验收完整流程。
+
+## 相关提交
+
+- `134514e` 安全兼容采购规格繁简匹配