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

New Issue

2026-08-11T11:34:46+08:00

ila commented

2026-08-11 11:34:46 +08:00

基本信息

类型：需求（第三方商品目录导入工具）
父级大工单：#14
所属 MVP / 版本：#15 / 商品目录数据接入后续
阶段：真实数据接入
依赖：#133、#141、#142
状态：待验收

要解决什么

raw_data/shopee_chanpin_1_已处理.xlsx、shopee_chanpin_2_已处理.xlsx、shopee_chanpin_3_已处理.xlsx 共 2075 个蝦皮商品、33049 条唯一规格，需要通过 POST /api/v1/integrations/catalog/batches 分批导入。文件是一行一个规格，同商品重复；没有真实蝦皮 SKU ID，也没有可靠的颜色/尺码维度名称，且不同文件的两个变种列顺序不一致，不能猜测结构化颜色尺码。

做什么 / 不做什么

做：新增独立 Python 命令行脚本读取三个工作簿，按商品聚合并分批提交蝦皮商品、原始组合规格、PDD 商品骨架及关联；支持预检、确定性批次 ID、重试、幂等重跑、清晰进度和汇总；补充自动化测试与使用文档。
不做：不把 Token 写入源码/参数默认值/日志/状态文件；不提交 raw_data ��业样本；不猜测颜色尺码、不伪造蝦皮 SKU ID 或 PDD 规格/价格；不修改 Admin 接口、数据库结构和 Client 四接口。

怎么做

新增 tools/import_catalog_xlsx.py，用 openpyxl 只读解析 在线商品；严格校验 22 列中的必需列、商品字段一致性、货源 ID 与 URL、规格非空和同商品规格唯一。
蝦皮商品映射标题、状态、主货号、缩略图和店铺显示名；两个变种属性按表格顺序组合为 spec_raw，sku_id 留空，颜色/尺码留空且 parse_ok=false。
PDD 只映射确定存在的货源 ID、规范化商品 URL和货源店铺名，规格列表留空；按货源 ID 批内去重，建立商品关联。
默认每批最多 200 个蝦皮商品；在发送前再校验总商品≤500、SKU≤5000、JSON≤5 MB，商品的全部 SKU 不跨批。
batch_id 使用转换器版本、文件内容哈希和批次序号生成；observed_at 使用批内 Excel 最大更新时间并附加 +08:00，保证相同文件重跑请求字节稳定。
接口地址从 --base-url 或 CMAUTOBUY_CATALOG_BASE_URL 获取，Token 只从 CMAUTOBUY_CATALOG_TOKEN 获取；网络、429 和可重试 5xx 指数退避，非重试错误立即停止。重新运行时已成功批次由服务端幂等重放。
新增脱敏临时工作簿单元测试，更新 docs/admin/10-商品目录接入接口.md 的脚本用法��

验收标准

三个真实样本预检得到 2075 个蝦皮商品、33049 条唯一规格，且不把商业数据加入 Git。
每个商品及其全部 SKU 位于同一批；PDD 商品按 ID 去重；所有批次满足 500/5000/5 MB 限制。
无 SKU ID 和无维度名时不伪造数据，spec_raw 稳定保留两个变种列顺序。
相同文件和参数重复运行生成完全相同的批次 ID、时间及 JSON，可安全断点重跑。
Token 只读环境变量且输出、异常和归档均不泄露 Token。
支持 dry-run、失败重试、非重试错误停止、逐批进度和最终计数。
自动化测试与三个真实 Excel dry-run 通过；Admin Go 1.23 回归通过；接口和数据库不变。

怎么验证

从仓库根目录执行 Python 单元测试；设置非敏感占位接口地址后对三个 raw_data 文件执行 --dry-run，核对商品、SKU、PDD、关联、批次数量和最大 JSON 大小；从 admin/ 使用固定 Go 1.23 执行 build/test/vet。真实提交时由负责人设置环境变量 Token 后运行��不在测试中调用生产写接口。

风险和回退

批量接口会写生产商品目录，首次真实提交前先执行 dry-run 并备份数据库。出现校验或业务冲突立即停止，不跳过失败批次；修正源文件后若请求内容变化，需使用新文件内容哈希生成的新批次 ID。回退脚本只需停止进程；已成功批次按接口 upsert 规则保留，不自动删除或覆盖人工数据。

实施记录

三个真实样本 dry-run：2075 个蝦皮商品、33049 条 SKU，生成 11 批，最大请求 1022285 字节；未发送生产请求。
Python 脱敏测试 5 项通过；固定 Go 1.23 build/test/vet 全部通过。
实现提交：acfa699
归档提交：e4385ac
归档：docs/task/146-商品目录Excel分批提交脚本.md
未验证：真实 Token 提交及生产数据库落库计数，须备份后执行。

生产执行范围变更（用户于 2026-08-11 明确确认）

目标扩展为部署当前 main 最新 Admin 到 185.216.248.75，部署前备份 autobuy；为生产服务生成并配置至少 32 字节随机 CMAUTOBUY_CATALOG_TOKEN（只写入 /etc/cmautobuy/admin.env，权限保持 600，不输出）；验证 HTTPS 商品目录路由和鉴权后，用本任务脚本提交三个 Excel 的 11 个幂等批次。遇到非重试错误停止，修正后继续；完成后核对导入记录成功数及生产商品/SKU/PDD/关联计数。

新增验收：

部署前数据库��份��在且 gzip 可读，旧发布路径可用于应用回切。
生产运行当前 main 对应二进制，服务、Nginx、MySQL 均 active，schema 自检通过。
专用 Token 仅存在于受限服务器环境文件和本次进程内，接口鉴权行为正确。
11 个批次全部 succeeded，脚本汇总 11/11；无失败或 processing 批次。
生产导入计数与脚本源数据核对，页面和既有 Client 接口健康。

生产执行结果

部署前备份：/opt/cmautobuy/backups/autobuy-before-e4385ac-20260811T034853Z.sql.gz，gzip 校验通过，权限 600。
生产发布：/opt/cmautobuy/releases/e4385ac/cmautobuy-admin，SHA-256 287e5b9484f9e827cbed3325c8c3c31b4209bca487692f1db6fa89fcd4ff9bd7。
目录 Token：服务器随机生成，仅保存于权限 600 的 /etc/cmautobuy/admin.env；明文未进入工单、日志或提交。
服务：Admin/MySQL/Nginx active，schema v10=1，公网错误 Token 返回 401 UNAUTHORIZED，近期致命错误 0。
导入：11 succeeded、0 failed、0 processing；蝦皮商品新增 2057/更新 18，SKU 新增 33049，PDD 新增 1883/更新 114，关联新增 2075。
生产归档更新提交：56b1a46。

## 基本信息 - 类型：需求（第三方商品目录导入工具） - 父级大工单：#14 - 所属 MVP / 版本：#15 / 商品目录数据接入后续 - 阶段：真实数据接入 - 依赖：#133、#141、#142 - 状态：待验收 ## 要解决什么 `raw_data/shopee_chanpin_1_已处理.xlsx`、`shopee_chanpin_2_已处理.xlsx`、`shopee_chanpin_3_已处理.xlsx` 共 2075 个蝦皮商品、33049 条唯一规格，需要通过 `POST /api/v1/integrations/catalog/batches` 分批导入。文件是一行一个规格，同商品重复；没有真实蝦皮 SKU ID，也没有可靠的颜色/尺码维度名称，且不同文件的两个变种列顺序不一致，不能猜测结构化颜色尺码。 ## 做什么 / 不做什么 - 做：新增独立 Python 命令行脚本读取三个工作簿，按商品聚合并分批提交蝦皮商品、原始组合规格、PDD 商品骨架及关联；支持预检、确定性批次 ID、重试、幂等重跑、清晰进度和汇总；补充自动化测试与使用文档。 - 不做：不把 Token 写入源码/参数默认值/日志/状态文件；不提交 `raw_data` ��业样本；不猜测颜色尺码、不伪造蝦皮 SKU ID 或 PDD 规格/价格；不修改 Admin 接口、数据库结构和 Client 四接口。 ## 怎么做 - 新增 `tools/import_catalog_xlsx.py`，用 `openpyxl` 只读解析 `在线商品`；严格校验 22 列中的必需列、商品字段一致性、货源 ID 与 URL、规格非空和同商品规格唯一。 - 蝦皮商品映射标题、状态、主货号、缩略图和店铺显示名；两个变种属性按表格顺序组合为 `spec_raw`，`sku_id` 留空，颜色/尺码留空且 `parse_ok=false`。 - PDD 只映射确定存在的货源 ID、规范化商品 URL和货源店铺名，规格列表留空；按货源 ID 批内去重，建立商品关联。 - 默认每批最多 200 个蝦皮商品；在发送前再校验总商品≤500、SKU≤5000、JSON≤5 MB，商品的全部 SKU 不跨批。 - `batch_id` 使用转换器版本、文件内容哈希和批次序号生成；`observed_at` 使用批内 Excel 最大更新时间并附加 +08:00，保证相同文件重跑请求字节稳定。 - 接口地址从 `--base-url` 或 `CMAUTOBUY_CATALOG_BASE_URL` 获取，Token 只从 `CMAUTOBUY_CATALOG_TOKEN` 获取；网络、429 和可重试 5xx 指数退避，非重试错误立即停止。重新运行时已成功批次由服务端幂等重放。 - 新增脱敏临时工作簿单元测试，更新 `docs/admin/10-商品目录接入接口.md` 的脚本用法�� ## 验收标准 - [x] 三个真实样本预检得到 2075 个蝦皮商品、33049 条唯一规格，且不把商业数据加入 Git。 - [x] 每个商品及其全部 SKU 位于同一批；PDD 商品按 ID 去重；所有批次满足 500/5000/5 MB 限制。 - [x] 无 SKU ID 和无维度名时不伪造数据，`spec_raw` 稳定保留两个变种列顺序。 - [x] 相同文件和参数重复运行生成完全相同的批次 ID、时间及 JSON，可安全断点重跑。 - [x] Token 只读环境变量且输出、异常和归档均不泄露 Token。 - [x] 支持 dry-run、失败重试、非重试错误停止、逐批进度和最终计数。 - [x] 自动化测试与三个真实 Excel dry-run 通过；Admin Go 1.23 回归通过；接口和数据库不变。 ## 怎么验证从仓库根目录执行 Python 单元测试；设置非敏感占位接口地址后对三个 `raw_data` 文件执行 `--dry-run`，核对商品、SKU、PDD、关联、批次数量和最大 JSON 大小；从 `admin/` 使用固定 Go 1.23 执行 build/test/vet。真实提交时由负责人设置环境变量 Token 后运行��不在测试中调用生产写接口。 ## 风险和回退批量接口会写生产商品目录，首次真实提交前先执行 dry-run 并备份数据库。出现校验或业务冲突立即停止，不跳过失败批次；修正源文件后若请求内容变化，需使用新文件内容哈希生成的新批次 ID。回退脚本只需停止进程；已成功批次按接口 upsert 规则保留，不自动删除或覆盖人工数据。 ## 实施记录 - 三个真实样本 dry-run：2075 个蝦皮商品、33049 条 SKU，生成 11 批，最大请求 1022285 字节；未发送生产请求。 - Python 脱敏测试 5 项通过；固定 Go 1.23 build/test/vet 全部通过。 - 实现提交：acfa699 - 归档提交：e4385ac - 归档：docs/task/146-商品目录Excel分批提交脚本.md - 未验证：真实 Token 提交及生产数据库落库计数，须备份后执行。 ## 生产执行范围变更（用户于 2026-08-11 明确确认）目标扩展为部署当前 main 最新 Admin 到 185.216.248.75，部署前备份 autobuy；为生产服务生成并配置至少 32 字节随机 CMAUTOBUY_CATALOG_TOKEN（只写入 /etc/cmautobuy/admin.env，权限保持 600，不输出）；验证 HTTPS 商品目录路由和鉴权后，用本任务脚本提交三个 Excel 的 11 个幂等批次。遇到非重试错误停止，修正后继续；完成后核对导入记录成功数及生产商品/SKU/PDD/关联计数。新增验收： - [x] 部署前数据库��份��在且 gzip 可读，旧发布路径可用于应用回切。 - [x] 生产运行当前 main 对应二进制，服务、Nginx、MySQL 均 active，schema 自检通过。 - [x] 专用 Token 仅存在于受限服务器环境文件和本次进程内，接口鉴权行为正确。 - [x] 11 个批次全部 succeeded，脚本汇总 11/11；无失败或 processing 批次。 - [x] 生产导入计数与脚本源数据核对，页面和既有 Client 接口健康。 ## 生产执行结果 - 部署前备份：/opt/cmautobuy/backups/autobuy-before-e4385ac-20260811T034853Z.sql.gz，gzip 校验通过，权限 600。 - 生产发布：/opt/cmautobuy/releases/e4385ac/cmautobuy-admin，SHA-256 287e5b9484f9e827cbed3325c8c3c31b4209bca487692f1db6fa89fcd4ff9bd7。 - 目录 Token：服务器随机生成，仅保存于权限 600 的 /etc/cmautobuy/admin.env；明文未进入工单、日志或提交。 - 服务：Admin/MySQL/Nginx active，schema v10=1，公网错误 Token 返回 401 UNAUTHORIZED，近期致命错误 0。 - 导入：11 succeeded、0 failed、0 processing；蝦皮商品新增 2057/更新 18，SKU 新增 33049，PDD 新增 1883/更新 114，关联新增 2075。 - 生产归档更新提交：56b1a46。

ila referenced this issue

2026-08-11 11:35:00 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-11 11:35:02 +08:00

[MVP] Admin 四模块可用闭环 #15

ila commented

2026-08-11 11:42:44 +08:00

实现完成，状态更新为待验收。

三个真实 Excel dry-run 通过：共 2075 个蝦皮商品、33049 条 SKU、11 个批次，最大请求约 1.02 MB；未调用生产写接口。Python 5 项测试及 Admin 固定 Go 1.23 build/test/vet 全部通过。

提交：acfa699、e4385ac。

实现完成，状态更新为待验收。三个真实 Excel dry-run 通过：共 2075 个蝦皮商品、33049 条 SKU、11 个批次，最大请求约 1.02 MB；未调用生产写接口。Python 5 项测试及 Admin 固定 Go 1.23 build/test/vet 全部通过。提交：acfa699、e4385ac。

ila commented

2026-08-11 11:54:43 +08:00

生产部署和真实导入完成，状态恢复为待验收。

Admin 发布 e4385ac，schema v10 完成，服务正常。
11/11 批次 succeeded，失败/进行中均为 0。
2075 个蝦皮商品处理、33049 条 SKU 新增、2075 条关联建立。
生产备份和 Token 权限已核对，敏感值未记录。
归档更新提交：56b1a46。

生产部署和真实导入完成，状态恢复为待验收。 - Admin 发布 e4385ac，schema v10 完成，服务正常。 - 11/11 批次 succeeded，失败/进行中均为 0。 - 2075 个蝦皮商品处理、33049 条 SKU 新增、2075 条关联建立。 - 生产备份和 Token 权限已核对，敏感值未记录。 - 归档更新提交：56b1a46。

ila referenced this issue

2026-08-11 14:23:11 +08:00

Admin：将确定的蝦皮非正式规格转换为正式规格 #152

ila referenced this issue

2026-08-11 14:40:54 +08:00

Admin：将确定的蝦皮非正式规格转换为正式规格 #152

ila commented

2026-08-12 10:31:57 +08:00