feat: 实现商品目录批量导入接口 (#133)

docs/README.md

@@ -50,6 +50,7 @@
 | 加字段、改表、写 SQL | [03 数据模型](admin/03-data-model.md) | [02 架构](admin/02-architecture.md) §2 分层 |
 | 改 Excel 导入 | [03 数据模型](admin/03-data-model.md) §3.3 | [00 术语表](admin/00-glossary.md) §3 upsert |
 | 改顺运宝同步 | [08 顺运宝接口](admin/08-顺运宝接口.md) | [03 数据模型](admin/03-data-model.md) |
+| 对接第三方商品目录脚本 | [10 商品目录接入接口](admin/10-商品目录接入接口.md) | [03 数据模型](admin/03-data-model.md) |
 | 把旧 Admin 数据迁移到 MySQL | [09 SQLite 单向迁移](admin/09-sqlite迁移到mysql.md) | [06 质量与安全](admin/06-quality-security.md) |
 | 改给 Client 的接口 | [04 Client 接口实现](admin/04-client-api.md) | [Client 侧契约](client/04-admin-api-contract.md) |
 | 和 Admin 联调、登记新设备 | [07 设备登记联调手册](admin/07-设备登记联调手册.md) | [Client 侧契约](client/04-admin-api-contract.md) §5 |
@@ -92,6 +93,7 @@
 | [07 设备登记联调手册](admin/07-设备登记联调手册.md) | **给 Client 开发者**：怎么让新设备登记成功 |
 | [08 顺运宝接口](admin/08-顺运宝接口.md) | 从抓包还原的外部 ERP 契约：登录、会话、货运单列表与明细 |
 | [09 SQLite 单向迁移](admin/09-sqlite迁移到mysql.md) | 只读演练、一次性导入、逐表核对和失败处理 |
+| [10 商品目录接入接口](admin/10-商品目录接入接口.md) | 第三方批量提交蝦皮、PDD 和商品关联的 JSON 契约 |
 
 ## 文档标注说明
 

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

@@ -0,0 +1,72 @@
+# 10 商品目录批量接入接口
+
+第三方脚本先把不同 Excel 归一化，再用本接口一次提交蝦皮商品、蝦皮 SKU、PDD
+商品及商品关联。接口只做 upsert，本批次没出现的数据不会被删除。
+
+## 1. 地址与鉴权
+
+- `POST /api/v1/integrations/catalog/batches`
+- 请求头：`Authorization: Bearer <专用 Token>`
+- 请求体上限 5 MB；每批商品总数最多 500，蝦皮 SKU 最多 5000。
+
+Token 通过 `CMAUTOBUY_CATALOG_TOKEN` 或未提交的 `config.yaml` 配置。未配置时接口
+返回 503；凭据错误返回 401。不要把 Token 放进 URL、日志或导入文件。
+
+## 2. 请求示例
+
+```json
+{
+  "schema_version": 1,
+  "batch_id": "source-file-20260811-001",
+  "observed_at": "2026-08-11T10:00:00+08:00",
+  "shopee_products": [
+    {"goods_id": "S-1", "title": "蝦皮上衣", "status": "NORMAL", "main_sku_code": "A01"}
+  ],
+  "shopee_skus": [
+    {"sku_id": "SKU-1", "goods_id": "S-1", "spec_raw": "黑色,M", "color": "黑色", "size": "M", "parse_ok": true, "sku_code": "A01-B-M"}
+  ],
+  "pdd_products": [
+    {
+      "goods_id": "P-1",
+      "url": "https://mobile.yangkeduo.com/goods.html?goods_id=P-1",
+      "title": "PDD 上衣",
+      "shop_name": "示例店铺",
+      "dimensions": [{"key": "color", "name": "颜色"}, {"key": "size", "name": "尺码"}],
+      "skus": [{"options": {"color": "黑色", "size": "M"}, "price_cent": 1299, "list_price_cent": 1599, "available": true}]
+    }
+  ],
+  "associations": [{"shopee_goods_id": "S-1", "pdd_goods_id": "P-1"}]
+}
+```
+
+金额单位固定为人民币分，不接受小数金额。`spec_raw` 必须原样提交。PDD 规格必须用
+结构化 `dimensions` 和 `skus`，第三方不能提交数据库内部的 `skus_json`。
+
+## 3. 写入与幂等规则
+
+- 整个批次在一个事务中写入：实体、SKU、关联任一步失败就全部回滚。
+- `(source, batch_id)` 是幂等键。请求字节相同则重放首次结果；同键不同内容返回 409。
+- 较旧的 `observed_at` 不覆盖较新的接口数据。
+- 蝦皮 upsert 不覆盖采购员维护的 PDD 链接；SKU 的 `is_manual` 不被接口改写。
+- 空关联可以建立、相同关联不重复写；已有不同 PDD 关联返回 409，绝不静默替换。
+- 批次缺少某条记录不表示删除，接口没有“全量覆盖”语义。
+
+成功响应包含批次状态和各类新增、更新、关联计数。相同请求重放时
+`replayed=true`。
+
+## 4. 错误格式
+
+```json
+{
+  "error": {
+    "code": "ASSOCIATION_CONFLICT",
+    "message": "蝦皮商品已经关联其他 PDD 商品",
+    "retryable": false,
+    "request_id": "调用方可选请求号",
+    "details": {}
+  }
+}
+```
+
+调用方应按 `code` 处理，不要解析中文 `message`。校验错误通常是 400/422，业务冲突
+是 409，临时服务错误是 500/503。响应和导入记录都不会回显 Token 或完整请求体。