# 295 颜色映射接入顺运宝与采购规格链路

- 类型：需求
- 父级大工单：#291
- 所属 MVP / 版本：蝦皮与 PDD 商品级颜色映射
- 状态：已完成
- 日期：2026-08-24
- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/295>

## 背景与目标

颜色映射不能直接表示可采购。需要把它作为现有完整规格解析的确定性输入：先约束 PDD 颜色，
再处理尺码和其他维度，只有唯一完整可购买组合才写入现有规格映射并进入采购主链路。

## 最终方案

- 增加不依赖 Gin 的幂等派生服务，可靠解析顺运宝“颜色,尺码”规格，读取当前蝦皮/PDD 商品
  对的有效颜色映射，并只处理 PDD 最新 `available=true` 的完整组合。
- 颜色限定后使用现有维度识别与确定性规格特征处理尺码；第三维度有多个值时，只有顺运宝
  原文能唯一指出其中一个才继续。最终不是恰好一个组合就返回普通“不生成”结论。
- 唯一结果写入既有 `spec_mappings`，来源为 `rule`、版本为 `color-spec-v1`，并向既有
  `spec_mapping_decisions` 追加成功决策。上下文覆盖顺运宝、PDD、颜色目标和规则版本。
- 人工完整映射永不覆盖；其他来源仍有效的完整映射继续保留。本规则自己的依据失效时删除
  当前派生结果，让现有阶段自然回到待匹配。
- 颜色保存、顺运宝明细写入和 PDD 采集结果回传三个写入事件在各自原事务中调用同一服务；
  数据库错误回滚原事务，重复上下文不重复更新或追加决策。
- 未改变处理阶段、采购校验、任务载荷或 Client 接口，不自动创建采购任务、不下单、不付款。

## 改了哪些

- `admin/service/color_spec_derivation.go`：实现单行、商品级和 PDD 商品级幂等派生。
- `admin/service/color_mapping.go`、`syb.go`、`submit.go`：接入三个事务写入事件。
- `admin/repository/mapping.go`：返回自动映射是否真正变化，并支持只删除本规则结果。
- `admin/repository/syb.go`、`shopee.go`：增加限定商品范围的事件查询。
- `admin/service/color_spec_derivation_test.go`：覆盖唯一、多候选、清除、幂等、人工保护和采集事件。
- `docs/admin/01-requirements.md`、`03-data-model.md`：记录采购边界与复用规则。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 有效颜色映射加唯一剩余维度时生成完整当前可购买映射 | 通过 |
| 尺码或第三维度不唯一时保持待匹配 | 通过 |
| 解析失败、映射缺失或目标失效时不猜测 | 通过 |
| PDD/SYB/颜色上下文进入规则版本，旧依据不会继续保留本规则结果 | 通过 |
| 人工和其他来源的有效完整映射不被覆盖 | 通过 |
| 三个写入事件调用同一幂等服务 | 通过 |
| 现有阶段和采购继续只读取完整规格映射 | 通过 |
| Client 契约、任务载荷及真实采购红线不变 | 通过 |

## 测试

- 执行的命令：`go test ./service -run TestUniqueColorAssistedChoice -count=1`；
  `go test ./... -count=1`；`go build ./...`；`go vet ./...`；`git diff --check`；
  使用 `GOTOOLCHAIN=go1.23.0` 再执行 `go build ./...`、`go test ./... -count=1`、`go vet ./...`。
- 结果：通过；Admin API/契约相关包包含在全量测试中且未修改 Client 契约。
- **没验证到的部分**：未连接独立 MySQL 8.4 `_test` 执行事务、并发和三个真实写入事件的
  数据库集成测试；对应测试已加入，在未设置 `CMAUTOBUY_MYSQL_TEST=1` 时按项目规则跳过。
  未执行生产迁移、真实顺运宝同步或真实 Client 采集回传。

## 相关提交

- `486a374` feat: 复用颜色映射生成完整采购规格 (#295)