281 Admin：规范 CSV 预检与安全入库

类型：需求
父级大工单：#14
所属 MVP / 版本：#15（商品目录接入后续批量数据准备）
状态：已完成，待验收
日期：2026-08-20
Gitea 工单：#281

背景与目标

#280 已导出 20 份规范 CSV。正式导入前需要按当前数据库预检，且已有蝦皮、SKU、PDD 和人工关联不能被第三方数据覆盖。

最终方案

商品目录批次请求增加 dry_run=true。Admin 在只读事务中返回预检计数与既有关联冲突，不写商品表，也不登记幂等批次。正式导入固定 fill_missing；收紧既有实现，使蝦皮标题/主货号、SKU 规格、PDD URL/标题/店铺/采集结果都不会被非空来源值覆盖。

新增 CSV 工具以流式方式按连续蝦皮商品组装批次。它默认必须选择 --dry-run 或 --apply，前者调用数据库预检，后者才写入；Token 仅从环境变量读取。实际 CSV 预组装为 212 批，最大 500 商品实体、5,000 SKU、1,142,989 字节。

改了哪些

admin/service/catalog_import.go：增加只读预检响应和关联冲突信息。
admin/repository/catalog_import.go：增加预检查询，并收紧 fill_missing 的非覆盖行为。
admin/service/catalog_import_test.go：覆盖预检无写入、关联冲突和已有字段不覆盖。
tools/import_thirdparty_catalog_csv.py：规范 CSV 流式预检/入库工具。
docs/admin/10-商品目录接入接口.md：补充 dry_run 和安全导入规则。

验收结果

验收标准	结果
预检不写业务表和导入记录	通过自动化测试。
既有不同 PDD 关联报告冲突且不替换	通过自动化测试。
`fill_missing` 不覆盖已有蝦皮/PDD 非空字段	通过自动化测试。
CSV 流式分批且满足接口上限	通过实际 20 CSV 预组装验证，212 批。
文档同步更新	通过。

测试

执行的命令：

cd D:\chengma\cmautobuy\admin
$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN

cd D:\chengma\cmautobuy
python -m py_compile tools\import_thirdparty_catalog_csv.py

结果：Go 全量构建和测试通过；Python 语法检查通过；全部 CSV 预组装满足批次上限。
没验证到的部分：新接口未部署到线上，因此尚未对生产 MySQL 执行真实预检，也未执行 --apply 写入。生产预检必须先部署本提交，再设置当前终端环境变量中的 Token 运行 --dry-run；确认报告后才能执行 --apply。

2.7 KiB Raw Blame History

281 Admin：规范 CSV 预检与安全入库

背景与目标

最终方案

改了哪些

验收结果

测试

相关提交

2.7 KiB

Raw Blame History