# 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` 安全兼容采购规格繁简匹配