Qingpu 商品库与工作区 API

本文档说明 Qingpu 铺货工作台中商品库与工作区选择器使用的接口。

货源媒体编辑

货源商品编辑抽屉通过来源媒体接口修改 canonical 事实层中的图片与视频。图片保存在 canonical.media.images,视频保存在 canonical.extra.videos;它们与工作区上传素材、生成图、发布排序和渠道视频保持分层。

  • GET /api/qingpu/listing/products/source-detail?productId=... 返回 canonical.media.images、sourceVideos,并在来源 SKU 中返回可用的 imageUrl。
  • POST /api/qingpu/listing/products/source-media 接收 productId、baseRevision、images 和 videos。图片必须保留至少 1 张、最多 50 张,数组首项作为来源主图;视频最多 10 条。请求使用 revision 乐观锁,冲突返回 409 与 currentRevision。
  • POST /api/qingpu/listing/products/source-media-upload 使用 multipart 的 productId 与 file 上传来源媒体。图片支持 JPEG、PNG、WebP,单文件不超过 10MB;视频支持 MP4、WebM、MOV、M4V,单文件不超过 50MB。上传成功返回稳定 assetId、mediaType 和托管 URL,最终仍需调用来源媒体保存接口写入 canonical。

删除来源图片时,服务端同步移除工作区 selectedImageAssetIds / generationReferenceImageIds / publishedImageAssetIds 中对应的原图引用;删除来源视频时会清理失效的 referenceVideoUrl。网页端既支持公网 http(s) 视频 URL,也支持本地视频文件。本地文件通过已鉴权的 Qingpu 统一上传服务写入 NuxtHub Blob 或部署环境的本地 uploads 目录,并立即以 media_type=video、meta.source=upload 登记到 qingpu_assets。

任务控制

  • 请求地址: /api/qingpu/listing/tasks/control
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key;只能操作当前用户自己的任务。

请求体

{
  "taskId": 123,
  "action": "pause"
}

action 支持 pause、resume、delete。运行中任务收到暂停或删除请求后,会在当前不可取消的远程调用完成后的安全检查点停止;暂停保留原任务进度、远程任务 ID、子任务账本和已生成资产,继续时不会从头创建新任务。删除只隐藏任务记录,不删除已经生成的资产。

成功响应

{
  "code": 0,
  "data": {
    "taskId": 123,
    "status": "pause_requested"
  }
}

状态还可能是 paused、queued 或原终态。只有真正进入 paused 后才能继续;重复操作或对终态任务执行暂停会返回 409,不存在或不属于当前用户的任务返回 404。

Listing 工作流账本

Listing 内容准备只以共享引擎 Workflow Registry 作为节点和依赖事实源。网页、扩展与桌面端统一提交云端 Workflow Run;attributes、translate、copy、images 是可单独执行和重试的 Task Run。上架文案与生图只依赖事实翻译成功,事实翻译只等待补参执行结束。

  • GET /api/qingpu/listing/tasks/workflow?workflowRunId=...:直接返回 Workflow Run 及其全部 Task,不受最近任务分页上限影响。
  • GET /api/qingpu/listing/tasks/attempts?taskId=...:返回该 Task 每一次不可覆盖的执行 Attempt 和逐项结果。

任务执行成功与业务就绪度分离。例如补参执行成功但补充 0/33 时,页面显示“已执行但仍不完整”,不会重新显示为“从未执行”。人工重试会新增 Attempt,旧结果、错误和起止时间均保留。

1. 获取商品列表

  • 请求地址: /api/qingpu/listing/products?page=1&limit=50&search=
  • 请求方法: GET
  • 权限要求: 已登录用户或 Bearer 租户 Key

查询参数

参数类型必填说明
pagenumber否页码,从 1 开始,默认 1。
limitnumber否每页条数,默认 20,最大 100。
searchstring否按商品标题或来源商品 ID 搜索。
workspaceOnlyboolean否传 true 时,只返回已经存在工作区行的商品。
showDeletedboolean否传 true 时,会把已软删商品一并返回;若同时传 workspaceOnly=true,还会带出 workspaceSoftDeleted。

成功响应

{
  "code": 0,
  "data": {
    "items": [
      {
        "productId": "p_123",
        "sourcePlatform": "1688",
        "sourceUrl": "https://detail.1688.com/offer/123.html",
        "sourceProductId": "123",
        "title": "Storage Box",
        "mainImageUrl": "https://example.com/image.png",
        "skuCount": 3,
        "categoryId": 1001,
        "categoryTypeId": 2001,
        "categoryName": "Home / Storage",
        "preprocessStatus": "generated",
        "revision": 12,
        "updatedAt": "2026-07-20T12:00:00.000Z",
        "softDeleted": false,
        "workspaceSoftDeleted": false
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

2. 删除商品

  • 请求地址: /api/qingpu/listing/products/delete
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

请求体

{
  "productIds": ["p_123", "p_456"]
}

成功响应

{
  "code": 0,
  "data": {
    "deletedCount": 2
  }
}

说明

  • 该接口会把 qingpu_listing_products.deleted_at 更新为当前时间。
  • 同时会向下传播到 workspaces / channel_drafts / image_assets,统一进入软删态。

3. 恢复商品

  • 请求地址: /api/qingpu/listing/products/restore
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

请求体

{
  "productIds": ["p_123"]
}

成功响应

{
  "code": 0,
  "data": {
    "restoredCount": 1
  }
}

说明

  • 该接口会把 qingpu_listing_products.deleted_at 清回 null。
  • 工作区、渠道草稿和图片资产仍按各自层级单独恢复,避免误把用户已经删除的下游内容全部自动拉回。

4. 恢复工作区行

  • 请求地址: /api/qingpu/listing/workspaces/restore
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

请求体

{
  "productId": "p_123"
}

成功响应

{
  "code": 0,
  "data": {
    "restoredCount": 1
  }
}

说明

  • 该接口会把 qingpu_listing_workspaces.deleted_at 清回 null。
  • 工作区选择器在进入一个已软删的工作区商品前,可以先调用该接口完成恢复。

5. 永久删除商品

  • 请求地址: /api/qingpu/listing/products/purge
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

请求体

{
  "productIds": ["p_123"]
}

成功响应

{
  "code": 0,
  "data": {
    "deletedCount": 1
  }
}

说明

  • 该接口只对已经处于软删态的商品生效。
  • 服务端会物理删除 qingpu_listing_products 中对应的商品行。
  • 同时会级联永久删除同一 productId 下的 qingpu_listing_workspaces / qingpu_listing_channel_drafts / qingpu_listing_image_assets。

6. 永久删除工作区行

  • 请求地址: /api/qingpu/listing/workspaces/purge
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

请求体

{
  "productId": "p_123"
}

成功响应

{
  "code": 0,
  "data": {
    "deletedCount": 1
  }
}

说明

  • 该接口只对已经处于软删态的工作区行生效。
  • 服务端会物理删除 qingpu_listing_workspaces 中对应的工作区行。
  • 不会连带删除货源商品和渠道草稿。

7. 读取与修改工作区 SKU

  • 请求地址: /api/qingpu/listing/skus
  • 请求方法: GET、POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

GET 查询参数

参数类型必填说明
productIdstring是铺货商品 ID。

POST 请求体

每次修改都必须把最近一次 GET 或 POST 响应中的 revision 作为 baseRevision 提交。

{
  "productId": "p_123",
  "baseRevision": 12,
  "op": "update",
  "variantId": "sku_1",
  "patch": {
    "priceRub": 1299,
    "stock": 20,
    "packageWeightG": 450
  }
}

支持 create、update、aspect、translation、fillDown、bulkPackaging、cardField、remove。数值字段传 null 表示清除 SKU 覆盖,回落到采集值或商品级兜底值。库存必须是大于等于 0 的整数;价格和包装尺寸重量必须是正数。

新增 SKU 使用 create。传入 sourceVariantId 时复制来源 SKU 的采购价、库存、包装、售价覆盖和平台规格覆盖;不传时创建空白手工 SKU。两种模式都不会复制 SKU 图片,图片使用新 SKU 自己的独立槽位。

{
  "productId": "p_123",
  "baseRevision": 12,
  "op": "create",
  "variantId": "manual-550e8400-e29b-41d4-a716-446655440000",
  "sourceVariantId": "sku_1",
  "optionValues": {
    "颜色": "墨绿色",
    "尺码": "L"
  },
  "patch": {
    "priceRub": 1299,
    "oldPriceRub": 1599,
    "stock": 20,
    "packageWeightG": 450
  },
  "aspects": [
    { "attributeId": 10096, "value": "Зеленый" }
  ]
}

成功响应

{
  "code": 0,
  "data": {
    "revision": 13,
    "rows": [],
    "dimensions": [],
    "cardFields": [],
    "modelNameColumn": null,
    "defaultMergeModelName": "p_123",
    "packagingFallback": {
      "depthCm": 20,
      "widthCm": 10,
      "heightCm": 5,
      "weightG": 450
    },
    "translation": {
      "title": "收纳盒",
      "description": "商品简介",
      "hashtags": "#收纳"
    }
  }
}

Revision 冲突响应

{
  "statusCode": 409,
  "message": "商品数据已更新",
  "data": {
    "currentRevision": 14
  }
}

网页端对即时编辑串行保存,遇到一次 409 时使用 currentRevision 重放当前操作。手工新增 SKU 保存在 listingWorkspace.manualOverrides.manualVariants,不会污染 canonical 来源事实;规格组合必须唯一。删除 SKU 只把 ID 追加到 excludedSkuIds,不会删除 canonical 货源变体或手工 SKU 记录,因此仍可恢复。

8. 获取渠道佣金规则

  • 请求地址: /api/qingpu/listing/commissions?channel=ozon
  • 请求方法: GET
  • 权限要求: 已登录用户或 Bearer 租户 Key

查询参数

参数类型必填说明
channelstring否渠道匹配器 Key,当前默认且支持 ozon。

成功响应

{
  "code": 0,
  "data": {
    "version": "Tarifs_CN_01_12_2025_1761720496",
    "source": "Tarifs_CN_01_12_2025_1761720496.xlsx / MP Tree Tarifs CN / RFBS",
    "tree": [
      {
        "value": "block-03-beauty",
        "label": "美容 / Beauty",
        "children": [
          {
            "value": "cat-029-clothing-and-accessories",
            "label": "服装和配饰 / Clothing & Accessories",
            "children": [
              {
                "value": "cat-029-clothing-and-accessories-rfbs-0-1500",
                "label": "RFBS 0 - 1500 RUB (12%)",
                "rate": 12,
                "mode": "RFBS",
                "band": "0 - 1500 RUB"
              }
            ]
          }
        ]
      }
    ]
  }
}

说明

  • 渠道工厂优先读取 ozon-commission-tree 远程规则包;远程不可用时回退到代码内置的官方佣金树。
  • 该接口主要供自动匹配失败后的手动纠正使用。已经保存佣金绑定时,页面默认收起选择器,不会反复要求用户选择子类。
  • 不支持的 channel 返回 400。

9. 更新类目并自动绑定佣金

  • 请求地址: /api/qingpu/listing/products/update
  • 请求方法: POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

请求体

{
  "productId": "p_123",
  "baseRevision": 12,
  "patch": {
    "generationReferenceImageIds": ["image_main", "image_side", "image_detail"],
    "category": {
      "categoryId": 17028922,
      "typeId": 97091543,
      "categoryName": "服装 / 女装 / 连衣裙"
    }
  }
}

成功响应

{
  "code": 0,
  "data": {
    "revision": 13,
    "commission": {
      "matched": true,
      "preserved": false,
      "source": "explicit-mapping",
      "binding": {
        "categoryPath": ["block-03-beauty", "cat-029-clothing-and-accessories"],
        "categoryLabels": ["美容 / Beauty", "服装和配饰 / Clothing & Accessories"],
        "tierLabel": "RFBS 0 - 1500 RUB (12%)",
        "rate": 0.12
      }
    }
  }
}

匹配与持久化语义

  • generationReferenceImageIds 独立保存生图参考原图槽位,不改变图片保留集合和发布排序。服务端强制当前主图置首并把总数限制为 5;提交时必须携带当前 baseRevision。
  • 当前规则包提供类目映射时,优先检查精确 categoryId:typeId(再回退 type/category id)映射;随后使用显式关键词映射和置信度不低于 0.8 的类目名称匹配。
  • 完整绑定快照保存在 workspace.pricing.commissionBinding。再次选择相同 Ozon 类目时,自动绑定和用户手工纠正过的绑定都会直接复用。
  • 切换 Ozon 类目时会清除旧绑定并重新匹配;无法可靠匹配时返回 matched: false,页面才展开手动选择器。
  • 只修改售价时,仅在已绑定佣金子类中重新选择价格档位,不会再次要求用户选类目。
  • 手工纠正同样采用 revision-safe 串行保存,遇到 409 时只使用服务端 currentRevision 自动重试一次。

10. 获取或启动图集蓝图

  • 请求地址: /api/qingpu/listing/blueprint
  • 请求方法: GET、POST
  • 权限要求: 已登录用户或 Bearer 租户 Key

GET 查询参数

参数类型必填说明
productIdstring否传入后,响应会附带该商品当前有效的 SKU 图片槽位。

SKU 槽位只根据未出现在 workspace.manualOverrides.excludedSkuIds 中的变体生成。同一个规格值只要仍被至少一个已选 SKU 使用,对应规格值图片槽位就会保留。

POST 请求体

{
  "productId": "p_123",
  "workMode": "generate",
  "mode": "full"
}

成功响应

{
  "code": 0,
  "data": {
    "chain": ["generate", "attributes", "blueprint"],
    "enqueued": true
  }
}

蓝图入队时从数据库工作区冻结当前主图和最多四张辅助参考图。任务开始、瞬时重试与批后补漏都使用同一快照,不会因排队期间用户改选参考图而漂移。SKU 图片仍只使用该 SKU 自身的规格图,不消费商品级参考图快照。商品主图和场景轮播任务保持不变;SKU 图片任务只为当前已选变体生成,被排除的 SKU 不会再进入生图队列。

11. 获取 Ozon 类目与类目资源

Ozon 完整类目树不再通过 API 返回。浏览器先读取小型 manifest /themes/qingpu/listing/ozon-categories/manifest.json,再下载其中带内容哈希的 tree.<hash>.json 静态资产。manifest 定期重新校验,哈希树文件按 immutable 永久缓存。紧凑元组结构只供网页客户端内部使用,不作为公开 API 协议。

搜索类目

  • 请求地址: /api/qingpu/listing/categories
  • 请求方法: GET
  • 权限要求: 已登录用户
参数类型必填说明
qstring是按空格拆词,在完整类目路径中进行 AND 匹配。
limitnumber否默认返回 20 条,硬上限 50 条。
{
  "code": 0,
  "data": {
    "items": [
      {
        "categoryId": 17028922,
        "typeId": 97091543,
        "name": "连衣裙",
        "path": "服装 > 女装 > 连衣裙"
      }
    ]
  }
}

传入 view=tree 会返回 400;任何调用方都不得再通过动态 API 传输完整类目树。

获取已选类目的属性资源

  • 请求地址: /api/qingpu/listing/categories/attributes
  • 请求方法: GET
  • 权限要求: 已登录用户
参数类型必填说明
categoryIdnumber是Ozon description category ID。
typeIdnumber是Ozon 叶子 type ID。

响应返回已选类目的完整属性定义,但只预取必填属性和规格轴属性的字典候选。体积较大的选填字典继续按需获取。

补拉单个属性字典

  • 请求地址: /api/qingpu/listing/categories/attribute-values
  • 请求方法: POST
  • 权限要求: 已登录用户
{
  "productId": "p_123",
  "attributeId": 85
}
{
  "code": 0,
  "data": { "count": 128 }
}

候选值会合并写入工作区类目快照。该接口只返回数量,前端重新读取工作区行,不直接接收大字典响应。

12. 按使用场景读取商品详情

原聚合详情接口拆为三个需要鉴权的 GET 接口。调用方必须按场景选择最小读模型:

使用场景接口返回范围
货源商品编辑/api/qingpu/listing/products/source-detail?productId=p_123货源标题、描述预览、价格、属性与 SKU 事实
工作台恢复/api/qingpu/listing/products/workspace-detail?productId=p_123素材选择、定价设置、生成资产与货源视频
买家侧预览/api/qingpu/listing/products/channel-preview?productId=p_123&channel=ozon可直接渲染的服务端归一化 ChannelPreviewModel

三个接口都只投影必要的 JSONB 路径,不返回原始抓取协议、完整 workspace、无关渠道/店铺草稿或 Base64 图片字段。

workspace-detail 不携带 Ozon categoryAttributes / attributeDictionaryValues。用户打开类目参数时,前端才通过 /api/qingpu/listing/products/workspace-category-resources?productId=p_123 读取属性定义;大字典候选继续通过单属性接口按需搜索,不随详情或类目资源接口全量返回。

其中的生成图片也只返回 assetId / url / slotKey / softDeleted / reuseMode / current 列表摘要,不携带可能很大的 editorScene。相同 slotKey 的资产属于同一卡位的历史版本;POST /api/qingpu/listing/images/select-version 接收 { productId, slotKey, assetId },原子切换一个未删除版本为当前图。重新生成每次创建新计划和新资产,只有成功后才自动选中新版,旧版继续保留。用户打开单张图片编辑器时,再通过 /api/qingpu/listing/images/editor-scene?productId=p_123&assetId=asset_123 按需读取该资产的编辑场景。

图片生成请求只表达渠道无关语义。POST /api/qingpu/listing/images/generate 接收 { productId, slotKey?, slotGoal?, assignTo?, referenceImageId? };referenceImageId 必须是当前商品自有的 canonical 来源图。服务端重建商品聚合后,统一调用共享引擎的渠道图片任务工厂,冻结不可变 v1 任务规格。普通生成与重新生成只引用 canonical 原图,SKU 生图只引用该规格自己的来源图,只有精修允许把当前生成图置于参考图首位。未注册渠道会明确失败,不会偷偷套用 Ozon 规则。一键蓝图提交时会为主图、每个轮播槽和每个 SKU 槽分别冻结 taskSpec;执行、即时重试、进程恢复与批后补漏都复用落库规格,不按当前 workspace 重新构造。

图片 worker 只接受 v1 taskSpec。该版本上线前必须清理或迁移旧 payload 创建且仍处于 queued/running 的 image_generate、blueprint 任务;由于尚未上线,运行时明确不保留旧结构兼容。登录后访问 GET /api/qingpu/listing/engine-version 可读取运行实例实际加载的 vendor 包名、版本、源码提交和构建时间,重启后可据此核验实例版本。

渠道预览优先读取 Ozon 模板草稿,必要时回退其他 Ozon 店铺草稿,并在服务端把 original:<imageId>、workspace 资产和生成资产引用解析为浏览器 URL。没有已提交草稿时,标题、描述、图集、属性与 SKU 统一在服务端按 workspace/canonical 回退;客户端不得自行猜测私有资产引用。

13. 保存渠道草稿与正式发布

POST /api/qingpu/listing/drafts 只读取当前 canonical/workspace 聚合,生成渠道快照、执行本地完整性与合卡冲突校验,并写入 qingpu_listing_channel_drafts。该接口不得刷新平台类目、下载平台字典、回写 workspace 或推进商品 revision。

真正的平台交互只发生在 POST /api/qingpu/listing/publish;只有 mode=live 才调用渠道发布驱动。草稿保存通过 publishSnapshot.workspaceRevision 锁定当前商品版本,若保存期间商品被并发修改则立即拒绝旧快照。

对话式上品与工作区一致性

对已采集商品,POST /api/qingpu/launch/intake、/api/qingpu/launch/copilot 与 /api/qingpu/launch/save 从当前登录用户的工作区重新读取来源事实、在售 SKU 和核价设置。预览与加工箱复用同一定价引擎,逐 SKU 采用采购价、重量、物流规则和显式售价覆盖;只改毛利率不回写包装,也不把派生建议价冻结成手工售价。

缺失的包装尺寸保持缺失,仅持久化本轮明确改变的包装值;保存和核价不得补入示例尺寸、重量或库存。新增无依据保修、技术参数或已排除 SKU 的文案声明,在写入前返回 422;工作区并发修改返回 409,生成或保存失败不得伪报预览成功。