64 lines
3.4 KiB
Markdown
64 lines
3.4 KiB
Markdown
# 146 Admin：编写三个已处理 Excel 的商品目录分批提交脚本
|
||
|
||
- 类型：需求
|
||
- 父级大工单：#14
|
||
- 所属 MVP / 版本：#15 / 商品目录数据接入后续
|
||
- 状态：已完成
|
||
- 日期：2026-08-11
|
||
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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 分批提交脚本
|