docs: 归档任务 #295

docs/task/295-颜色映射接入顺运宝与采购规格链路.md

@@ -0,0 +1,63 @@
+# 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)