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

# 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",
  "update_policy": "fill_missing",
  "shopee_products": [
    {"goods_id": "S-1", "title": "蝦皮上衣", "status": "NORMAL", "main_sku_code": "A01", "image_url": "https://img.example.com/S-1.jpg", "shop_name": "蝦皮示例店铺"}
  ],
  "shopee_skus": [
    {"sku_id": null, "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`。

`sku_id` 是可选的真实蝦皮 SKU ID；来源文件没有该值时省略、传 `null` 或空字符串，
不得自行生成。系统用内部主键和 `goods_id + spec_key` 保持记录身份，后续取得真实 ID
会补到原记录，不会重复新增。

`image_url` 和 `shop_name` 可选。图片只接受不含用户信息和明显凭据参数的完整
HTTP/HTTPS URL，最长 2048 字节；店铺名最长 500 个字符。Admin 只保存地址并由浏览器
懒加载，不会在服务端下载或代理图片。

## 3. 写入与幂等规则

- 整个批次在一个事务中写入：实体、SKU、关联任一步失败就全部回滚。
- `(source, batch_id)` 是幂等键。请求字节相同则重放首次结果；同键不同内容返回 409。
- `update_policy` 可省略，默认 `fill_missing`：
  - `insert_only`：只新增，已有规格不修改；
  - `fill_missing`：只补颜色、尺码、建议、SKU 编码等空字段；
  - `overwrite_same_source`：只有来源相同且 `observed_at` 更新时才覆盖来源字段。
- 较旧的 `observed_at` 不覆盖较新的接口数据，任何策略都不能覆盖 `is_manual=1`。
- `spec_raw` 和由它生成的规格身份不被更新；同商品同规格出现不同真实 SKU ID 返回 409。
- 蝦皮主图和店铺名也遵循本批次策略，但各自独立记录来源、观测时间和人工保护；
  空值永不清除现有值。顺运宝观测图片不参与蝦皮主图更新。
- 蝦皮 upsert 不覆盖采购员维护的 PDD 链接；SKU 的 `is_manual` 不被接口改写。
- 空关联可以建立、相同关联不重复写；已有不同 PDD 关联返回 409，绝不静默替换。
- 批次缺少某条记录不表示删除，接口没有“全量覆盖”语义。

成功响应包含批次状态以及 SKU 新增、补空、同来源更新、人工跳过、旧数据跳过等计数。相同请求重放时
`replayed=true`。

## 4. 错误格式

```json
{
  "error": {
    "code": "ASSOCIATION_CONFLICT",
    "message": "蝦皮商品已经关联其他 PDD 商品",
    "retryable": false,
    "request_id": "调用方可选请求号",
    "details": {}
  }
}
```

调用方应按 `code` 处理，不要解析中文 `message`。校验错误通常是 400/422，业务冲突
是 409，临时服务错误是 500/503。响应和导入记录都不会回显 Token 或完整请求体。

## 5. schema v8～v10 发布与回退

发布前先备份生产库，并在 MySQL 8.4、库名以 `_test` 结尾的测试库演练 v7→v8→v9→v10。
迁移只增加列和唯一索引，既有 `sku_id` 继续作为内部主键，因此历史引用不变；若检测
到同商品重复 `spec_key`，迁移会停止且不记录 v8，必须人工确认，不能自动合并。

若数据库已经记录 v8 或 v9，但缺少 `field_sources`、`field_observed_at` 等 v8 结构，
或缺少图片、店铺人工标记约束等 v9 结构，v10 会幂等重放两版迁移并只回填空值。
不要通过删除迁移版本、清库或手工伪造结构来绕过自检；修复完成且 v8/v9 形状均
正确后，程序才会记录 v10。

旧版 Admin 不理解无真实 SKU ID 的新记录。应用回退前应暂停目录接口并确认没有此类
记录；不要删除 v8 列或把内部主键复制成伪造的外部 SKU ID。