# 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)