WuYongJie/gongxiangp2

Fork 0

chenpei 96fcf312cb feat: support task detail barcode assets for product platform

2026-04-22 15:47:58 +08:00

4.3 KiB

Raw Blame History

自动上架平台成套入库通知接口

更新时间：2026-04-22

目标

这组对接能力用于让素材库在出现新的「任务-详情全套素材」时，主动通知自动上架平台。

自动上架平台收到通知后：

先用通知里自带的预览图做展示或人工确认
真正需要上架时，再按 materialId 调素材库资源接口拉正式资源

触发规则

当前只对 任务-详情 生效
触发条件是：同一条素材记录第一次达到「全套入库完成」
创建时就是全套，会触发 1 次
后续补齐到全套，会触发 1 次
已经全套后再次编辑，不会重复触发

主识别键

主键：materialId
附带字段：taskNo

说明：

taskNo 可能为空
不能把 taskNo 当成这组通知能力的唯一主键

通知方式

方法：POST
方向：素材库服务端主动调用自动上架平台提供的回调地址
Content-Type：application/json

回调地址、鉴权方式、是否启用，由素材库后台配置。

当前支持的回调鉴权方式：

无鉴权
Bearer Token
自定义 Header

通知事件

eventType: task-detail.full-set.ready

通知 payload

顶层字段

字段	说明
`eventId`	事件唯一 ID
`eventType`	固定为 `task-detail.full-set.ready`
`materialId`	素材记录 ID
`materialType`	当前固定为 `任务-详情`
`taskNo`	任务号，可为空
`productModel`	SPU
`categoryName`	店铺
`shopName`	店铺，当前与 `categoryName` 相同
`sceneName`	场景
`isFullSet`	是否全套
`occurredAt`	事件发生时间
`pullUrl`	正式资源拉取地址
`coverPreviewUrl`	封面预览图地址
`previewAssets`	分组预览图

预览图字段

previewAssets.main、previewAssets.sku、previewAssets.detail 中的每一张图，至少包含：

字段	说明
`url`	预览图地址
`fileName`	文件名
`sortOrder`	顺序

通知示例

{
  "eventId": "evt-20260325-0001",
  "eventType": "task-detail.full-set.ready",
  "materialId": "35d8644b-1e09-4ce8-9bb0-c529b39ba52e",
  "materialType": "任务-详情",
  "taskNo": null,
  "productModel": "XG025503",
  "categoryName": "旗舰店",
  "shopName": "旗舰店",
  "sceneName": "客厅",
  "isFullSet": true,
  "occurredAt": "2026-03-25T08:00:00.000Z",
  "pullUrl": "https://sc.jiansun.vip/api/external/product-assets?materialId=35d8644b-1e09-4ce8-9bb0-c529b39ba52e",
  "coverPreviewUrl": "https://s3.jiansun.vip/gongxiangpan/public-display/task-detail/material-1/cover.webp",
  "previewAssets": {
    "main": [
      {
        "url": "https://s3.jiansun.vip/gongxiangpan/public-display/task-detail/material-1/main/1.webp",
        "fileName": "main-1.webp",
        "sortOrder": 0
      }
    ],
    "sku": [
      {
        "url": "https://s3.jiansun.vip/gongxiangpan/public-display/task-detail/material-1/sku/1.webp",
        "fileName": "sku-1.webp",
        "sortOrder": 1
      }
    ],
    "detail": [
      {
        "url": "https://s3.jiansun.vip/gongxiangpan/public-display/task-detail/material-1/detail/1.webp",
        "fileName": "detail-1.webp",
        "sortOrder": 2
      }
    ]
  }
}

正式资源拉取

自动上架平台后续拉正式资源时，统一调用：

GET /api/external/product-assets?materialId={materialId}

请求头：

X-API-Key: your-api-key

说明：

这组资源接口和 AI 生图平台共用同一套外部接口
当前推荐自动上架平台统一按 materialId 查询
原来的 taskNo 查询仍兼容，但不建议把它当这组能力的主键

成功判定

回调返回 2xx：视为成功
回调超时、网络失败、非 2xx：视为失败

重试与补发

通知发送是异步执行，不阻塞素材入库成功
失败后会自动重试
超过重试上限后，会进入待人工处理
素材库后台支持手工补发

对接建议

自动上架平台接到通知后，先按 eventId + materialId 做幂等去重
预览图仅用于预览，不建议直接把通知里的预览图当正式上架源文件
真正上架前，请再按 materialId 调正式资源接口获取完整资源
如果回调接口会做验签或 Header 校验，请在素材库后台配置对应鉴权方式

4.3 KiB Raw Blame History Unescape Escape