cmautobuy/docs/task/146-商品目录Excel分批提交脚本.md

146 Admin：编写三个已处理 Excel 的商品目录分批提交脚本

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#15 / 商品目录数据接入后续
• 状态：已完成
• 日期：2026-08-11
• Gitea 工单：#146

背景与目标

三个已处理工作簿是一行一个蝦皮规格，共 2075 个蝦皮商品、33049 条唯一规格， 同时包含 PDD 商品 ID、链接、店铺以及两边的关联。需要先把重复的商品行聚合，再按 商品目录接口的商品数、SKU 数和请求体大小限制安全分批，并允许失败后幂等重跑。

最终方案

新增独立 Python 命令行工具。工具以只读方式解析 在线商品 工作表，严格检查列、 固定字段、规格唯一性和 PDD ID/URL 一致性；按蝦皮商品聚合，使一个商品的全部规格 不跨批，并按 PDD ID 在批内去重。默认每批最多 200 个蝦皮商品，同时动态检查接口的 500 商品、5000 SKU、5 MB 上限。

文件没有真实蝦皮 SKU ID，也没有可判断两个变种列含义的维度名称。工具只按原列顺序 组合 spec_raw，不填写 SKU ID、颜色、尺码或 PDD 规格价格。PDD 链接去掉跟踪参数， 只保留稳定的 goods_id。

批次 ID 同时包含转换器版本、文件内容、批量大小和更新策略的摘要，观测时间取批内 Excel 最大更新时间；相同文件和参数会产生完全相同的请求。Token 只读取环境变量， 临时错误指数退避，业务错误立即停止。实现与建单方案一致。

改了哪些

• tools/import_catalog_xlsx.py：Excel 聚合、批次规划、dry-run、鉴权提交、重试和汇总。
• tools/test_import_catalog_xlsx.py：脱敏工作簿的聚合、幂等、分批、冲突和重试测试。
• tools/requirements-catalog-import.txt：固定 openpyxl 版本。
• docs/admin/10-商品目录接入接口.md：补充安装、预检、真实提交和断点重跑说明。

验收结果

验收标准	结果
三个真实样本得到 2075 个蝦皮商品、33049 条唯一规格	通过
商品 SKU 不跨批，PDD 批内去重，全部批次满足三项接口限制	通过；共 11 批，最大请求 1022285 字节
不伪造 SKU ID、颜色尺码、PDD 规格和价格	通过
相同文件和参数生成相同批次 ID、时间和 JSON	通过
不同批量大小或更新策略使用不同批次 ID	通过
Token 只读取环境变量且不输出	通过
dry-run、临时错误重试、业务错误停止和进度汇总可用	通过
Python 自动化测试和 Admin Go 1.23 回归通过	通过

测试

• 执行的命令：python -m unittest tools/test_import_catalog_xlsx.py -v。
• 结果：5 个测试通过。
• 执行的命令：python tools/import_catalog_xlsx.py --dry-run。
• 结果：三个真实样本解析成功，分别生成 5、5、1 个批次；最大请求分别为 1022285、794046、350890 字节，未发送请求。
• 执行的命令：在 admin/ 使用 GOTOOLCHAIN=go1.23.0 执行 go build ./...、go test ./... -count=1、go vet ./...。
• 结果：全部通过。
• 没验证到的部分：未使用真实 Token 调用生产写接口；未在生产数据库核对 11 个批次的落库计数和导入记录，须在备份后由负责人执行真实提交。

相关提交

• acfa699 增加商品目录 Excel 分批提交脚本