docs: 归档任务 #193

docs/task/193-店铺规格只读对比.md

@@ -0,0 +1,53 @@
+# 193 Admin：生成指定蝦皮店铺与关联 PDD 的规格对比报告
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15
+- 状态：已完成
+- 日期：2026-08-12
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/193>
+
+## 背景与目标
+
+在正式把 `qwg8fkb044` 店铺的蝦皮正式规格补入关联 PDD 数据前，先只读核对两边数据，避免错误关联、歧义规格或无价格数据被批量覆盖。
+
+## 最终方案
+
+增加独立命令 `compare-shop-specs`：按店铺名精确读取蝦皮商品、正式规格及其明确关联的 PDD 商品，在内存中比较颜色和尺码组合并输出 JSON 报告。命令只有查询能力，没有 `--apply` 参数，也不会修改数据库。
+
+多个蝦皮商品关联同一个 PDD 商品时，若蝦皮正式规格集合不一致，统一标记为歧义，不进入后续自动回填候选。报告只包含商品编号、分类和数量，不包含标题、规格原文、价格或凭据。
+
+实际 dry-run 共检查 2075 件商品：1917 件关联 PDD 暂无可比较规格，155 件没有可用蝦皮正式规格，3 件两边规格均存在但组合不同。因此本工单没有直接批量修改 PDD 数据，正式回填需基于该结果另行确认范围。
+
+## 改了哪些
+
+- `admin/cmd/compare-shop-specs/main.go`：增加只读命令入口和本机 JSON 输出。
+- `admin/repository/spec_compare.go`：增加按店铺精确查询规格对比来源的只读查询。
+- `admin/service/spec_compare.go`：增加规格集合比较、差异分类和共用 PDD 歧义识别。
+- `admin/service/spec_compare_test.go`：覆盖相同、差异、未关联和共用 PDD 歧义场景。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 只处理精确店铺 `qwg8fkb044`，并严格通过 `pdd_goods_id` 关联 | 通过 |
+| 只比较正式颜色、尺码组合，不修改价格和库存 | 通过 |
+| 对缺数据、差异和多对一歧义进行分类 | 通过 |
+| 命令无写库和应用参数，报告不包含规格原文及价格 | 通过 |
+| 使用现有数据库生成实际 dry-run 汇总 | 通过 |
+
+## 测试
+
+- 执行的命令：`$env:GOTOOLCHAIN="go1.23.0"; go vet ./...; go build ./...; go test ./... -count=1`
+- 结果：全部通过。
+- 执行的命令：`go run ./cmd/compare-shop-specs --shop qwg8fkb044 --output <系统临时目录>/cmautobuy_qwg8fkb044_spec_compare.json`
+- 结果：成功生成 2075 件商品的只读对比报告。
+- **没验证到的部分**：没有执行任何正式规格回填或数据库写入；这是下一阶段工作，不属于本工单范围。
+
+## 遗留问题
+
+需要用户根据 dry-run 汇总确认正式回填范围和无价格 PDD 规格的保存方式，再另建写数据工单。
+
+## 相关提交
+
+- `cf1d0ab` 增加店铺规格只读对比工具