cmautobuy/docs/task/281-第三方规范csv预检与安全入库.md

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。

相关提交

• fe64d3b feat: 规范 CSV 预检与安全入库 (#281)