# 226 Admin：用三个蝦皮 Excel 最大价回填关联 PDD 正式价格

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

## 背景与目标

三个已处理 Excel 中包含蝦皮商品价格及蝦皮与 PDD 商品的关联。目标是仅针对这些文件中 `qwg8fkb044` 店铺的数据，按价格区间最大值换算人民币价格，回填到符合安全条件的 PDD SKU；回填成功后将 PDD 商品状态改为已采集，以便进入后续人工审核和采购流程。

## 最终方案

- 新增一次性命令 `backfill-xlsx-pdd-prices`，只读取固定白名单中的三个 Excel 文件，不接受任意文件名。
- 每个蝦皮商品取价格区间最大值；多个蝦皮商品关联同一 PDD 商品时，再取全局最大值。
- 按 `台币价格 ÷ 10 × 100` 换算为人民币分，使用正数四舍五入。例如 `249` 回填为 `2490` 分。
- 只更新未删除、规格来源为 `shopee_backfill`、规格 JSON 有效且全部 SKU 尚无正式价格、可售状态仍为未知、采集状态为待采集或采集失败的 PDD 商品。
- 写入每个 SKU 的 `price_cent`，保留 `list_price_cent`、库存和可售状态；同时把商品改为 `collected`，清除原采集错误和产物字段并记录采集时间。
- 已有正式价格、已采集、规格来源不同、规格为空或 JSON 无效的数据全部跳过，不新增字段或数据表。
- 更新使用单事务和原值乐观锁；任意一行冲突时整批回滚。正式执行前保留完整数据库备份和逐商品回退备份。
- Excel 价格只作为本次计算来源。当前蝦皮商品表没有正式价格字段，因此不向蝦皮表增加价格字段，也不触发真实下单或付款。

## 改了哪些

- `admin/cmd/backfill-xlsx-pdd-prices/main.go`：新增固定文件、默认预演、显式执行、备份和结果汇总的一次性工具。
- `admin/repository/price_backfill.go`：新增候选数据查询和带乐观锁的事务更新。
- `admin/service/xlsx_price_backfill.go`：实现 Excel 解析、价格换算、共享 PDD 去重取最大值、安全候选判定和回填计划。
- `admin/service/xlsx_price_backfill_test.go`：覆盖价格解析、白名单、店铺过滤、共享关联、安全跳过、字段保留和事务回滚。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 仅处理三个指定 Excel 中 `qwg8fkb044` 店铺的数据 | 通过 |
| 价格区间取最大值，共享 PDD 再取全局最大值，并按约定换算为分 | 通过 |
| 只更新安全候选，不覆盖任何已有正式价格 | 通过 |
| 回填 `price_cent` 后把 PDD 商品状态改为已采集 | 通过 |
| 保留标价、库存和可售状态，不新增字段或表 | 通过 |
| 默认预演，正式执行具备备份、事务和冲突回滚 | 通过 |
| 生产执行后不存在仍可回填的候选数据 | 通过 |

生产执行结果：

- Excel 共读取 33,049 行，解析到 2,075 个蝦皮商品和 1,883 个关联 PDD 商品。
- 实际更新 1,735 个 PDD 商品、27,537 个 SKU；所有被更新 SKU 均已填写 `price_cent`，对应 PDD 商品均为已采集。
- 蝦皮商品 `24948397488` 关联的 PDD 商品 `763183548813` 已回填为 `2490` 分，并改为已采集。
- 跳过 6 个原本已采集商品、141 个规格为空或 JSON 无效商品、1 个规格来源不符合条件的商品。
- 非目标店铺的 22 个关联 PDD 商品在执行前后数量和价格校验和一致。
- 完整业务库备份：`/opt/cmautobuy/backups/autobuy-before-226-20260814T083844Z-notablespaces.sql.gz`，已通过 gzip 完整性检查。
- 逐商品回退备份：`/tmp/cmautobuy_xlsx_price_backup_509969788.json`，共 1,735 项，权限为 `0600`。
- 服务器上的临时 Excel 副本已删除；一次性程序保留在 `/opt/cmautobuy/maintenance/226-7055519`。

## 测试

- 执行的命令：
  - `cd admin && go test ./... -count=1`
  - `cd admin && go vet ./...`
  - Linux amd64 交叉编译一次性程序
  - 生产环境先 dry-run，再执行 `./backfill-xlsx-pdd-prices -dir ./input -apply`，随后再次 dry-run
  - 查询生产数据库核对商品数、SKU 数、空价格、标价、可售状态、目标示例和非目标店铺校验和
  - 检查 `cmautobuy-admin` 服务状态和本机 `/login` HTTP 状态
- 结果：全部通过。执行后再次预演候选数为 0；Admin 服务保持运行，登录页返回 HTTP 200。
- **没验证到的部分**：未使用登录后的浏览器逐项查看 PDD 列表；未创建真实采购任务、未在 Client 真机采集，也未执行下单或付款。

## 遗留问题

141 个规格为空或 JSON 无效的 PDD 商品以及 1 个非 `shopee_backfill` 规格来源的商品未被本次回填修改，需按其各自数据问题另行处理。

## 相关提交

- `7055519` feat: 回填三个Excel关联PDD正式价格 (#226)