cmautobuy/docs/task/194-蝦皮规格回填PDD.md

# 194 Admin：将指定蝦皮店铺正式规格补入关联 PDD 空规格

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#15
- 状态：已完成
- 日期：2026-08-12
- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/194>

## 背景与目标

#193 确认 `qwg8fkb044` 店铺大量商品已经关联 PDD，但 PDD 尚无规格。用户确认允许用蝦皮正式颜色、尺码创建规格骨架，同时不得猜测价格和库存，也不得覆盖已有或异常的 PDD 规格。

## 最终方案

增加默认 dry-run 的独立命令 `backfill-shop-pdd-specs`。它只处理店铺名精确匹配、PDD 关联有效、蝦皮存在正式规格且 PDD 规格为空的商品；只有传入 `--apply` 才写库。

规格骨架保留颜色、尺码组合，价格字段为 `null`，库存使用 `availability_status=unknown`，不写 `available=true/false`，并用 `spec_source=shopee_backfill` 标记来源。已有规格、非法 JSON、软删除、无正式规格及多对一规格歧义均跳过。

写入前在本机临时目录保存原值备份；正式更新在单个事务中进行，并用原始 `skus_json` 作乐观锁，目标被并发修改时整批回滚。商品和规格拆成两次查询，避免把较大的 PDD JSON 随每个蝦皮 SKU 重复传输。

实际执行结果：1917 件蝦皮商品去重后对应 1738 件 PDD，全部完成规格骨架回填。155 件没有正式蝦皮规格、3 件已有 PDD 规格，均保持不变。回填后复查候选为 0。

## 改了哪些

- `admin/cmd/backfill-shop-pdd-specs/main.go`：增加 dry-run、显式 apply、本机备份和汇总输出。
- `admin/repository/spec_compare.go`：优化只读查询，并增加带原值乐观锁的参数化更新。
- `admin/repository/spec_compare_test.go`：验证原值变化时不会覆盖。
- `admin/service/spec_backfill.go`：增加候选判定、规格骨架、歧义跳过、事务应用和回填复核。
- `admin/service/spec_backfill_test.go`：覆盖未知价格库存、已有数据保护、多对一歧义、骨架识别和事务回滚。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 默认 dry-run，只有显式 `--apply` 才写库 | 通过 |
| 仅处理精确店铺、有效关联、正式规格存在且 PDD 规格为空的商品 | 通过 |
| 颜色尺码已写入，价格为 `null`，库存保持未知 | 通过 |
| 已有、异常、软删除、无正式规格和多对一歧义数据不覆盖 | 通过 |
| 单事务写入并使用原值乐观锁 | 通过 |
| apply 后复核 1738 件 PDD 已回填且候选为 0 | 通过 |

## 测试

- 执行的命令：`$env:GOTOOLCHAIN="go1.23.0"; go vet ./...; go build ./...; go test ./... -count=1`
- 结果：全部通过。
- 执行的命令：`go run ./cmd/backfill-shop-pdd-specs --shop qwg8fkb044`
- 结果：apply 前候选 1738 件 PDD；apply 后候选 0，已回填 1738 件。
- 执行的命令：`go run ./cmd/backfill-shop-pdd-specs --shop qwg8fkb044 --apply`
- 结果：事务提交成功，本机回退备份生成成功。
- **没验证到的部分**：没有把回填骨架当作 PDD 实时价格或库存使用；这些字段按需求保持未知，后续仍需真实采集才能补齐。

## 遗留问题

155 件蝦皮正式规格不可用、3 件已有 PDD 规格与蝦皮规格不一致，本工单按确认范围保留待人工补充，没有自动覆盖。

## 相关提交

- `8f7fb09` 回填店铺关联 PDD 空规格