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

docs/admin/10-商品目录接入接口.md

@@ -20,6 +20,7 @@ Token 通过 `CMAUTOBUY_CATALOG_TOKEN` 或未提交的 `config.yaml` 配置。
   "batch_id": "source-file-20260811-001",
   "observed_at": "2026-08-11T10:00:00+08:00",
   "update_policy": "fill_missing",
+  "dry_run": false,
   "shopee_products": [
     {"goods_id": "S-1", "title": "蝦皮上衣", "status": "NORMAL", "main_sku_code": "A01", "image_url": "https://img.example.com/S-1.jpg", "shop_name": "蝦皮示例店铺"}
   ],
@@ -67,6 +68,17 @@ HTTP/HTTPS URL，最长 2048 字节；店铺名最长 500 个字符。Admin 只
 - 空关联可以建立、相同关联不重复写；已有不同 PDD 关联返回 409，绝不静默替换。
 - 批次缺少某条记录不表示删除，接口没有“全量覆盖”语义。
 
+### 3.1 数据库预检
+
+请求中的 `dry_run` 设为 `true` 时，接口只在只读事务中检查当前数据库，不登记
+`catalog_import_runs`，也不写入商品、SKU、PDD 或关联。响应 `status` 为
+`previewed`，`counts` 用于显示预计新增或现有记录数量；`conflicts` 列出同一蝦皮商品
+已有不同 PDD 关联的业务 ID。正式导入仍会重新执行相同的非覆盖和关联冲突判断。
+
+第三方规范 CSV 导入固定使用 `fill_missing`：已有蝦皮商品、SKU 和 PDD 商品的非空字段
+不被覆盖；PDD 已采集的标题、店铺、规格、价格和状态不被第三方 CSV 修改。相同关联
+幂等跳过，不同关联返回冲突，绝不替换。
+
 成功响应包含批次状态以及 SKU 新增、补空、同来源更新、人工跳过、旧数据跳过等计数。相同请求重放时
 `replayed=true`。