docs: 归档任务 #281

2026-08-20 14:41:26 +08:00
parent fe64d3b3c7
commit efad2eadf4
1 changed files with 56 additions and 0 deletions
@@ -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)