diff --git a/docs/task/281-第三方规范csv预检与安全入库.md b/docs/task/281-第三方规范csv预检与安全入库.md new file mode 100644 index 0000000..a979e12 --- /dev/null +++ b/docs/task/281-第三方规范csv预检与安全入库.md @@ -0,0 +1,56 @@ +# 281 Admin:规范 CSV 预检与安全入库 + +- 类型:需求 +- 父级大工单:#14 +- 所属 MVP / 版本:#15(商品目录接入后续批量数据准备) +- 状态:已完成,待验收 +- 日期:2026-08-20 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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 批。 | +| 文档同步更新 | 通过。 | + +## 测试 + +- 执行的命令: + + ```powershell + 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)