joey5628/atlas-seller-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ai-edit): 开发 AI 填报功能

Browse Source
This commit is contained in:
R524809
2026-09-23 17:18:09 +08:00
parent 95a2a37f1b
commit b3958166dd
35 changed files with 2832 additions and 278 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/product-editor-and-publishing.md
+12 -18
View File
@@ -1,6 +1,6 @@
# 商品编辑与首次上架 API
> M3.0～M3.4 已实现编辑上下文、草稿、SKU、来源素材、类目和动态属性。平台目录刷新方案第 1～4 步已把类目树、类型属性、字典读取及发布预检迁至平台级缓存：编辑器按需刷新，首次发布预检只刷新当前类型和实际使用的字典。素材选择已实现；定价确认、AI 任务、真正调用 Ozon 的首次发布 job 仍是冻结契约，尚未实现。
> M3.0～M3.4 已实现编辑上下文、草稿、SKU、来源素材、类目和动态属性。平台目录刷新方案第 1～4 步已把类目树、类型属性、字典读取及发布预检迁至平台级缓存：编辑器按需刷新，首次发布预检只刷新当前类型和实际使用的字典。AI 填报任务已实现；定价确认和真正调用 Ozon 的首次发布 job 仍未实现。
> 此处的商品始终是采集箱内的 Atlas 草稿。所有平台范围接口要求 `X-Atlas-Platform-Id`。商品通用资料可以跨平台复用；`product_platform_profile`、SKU 首次导入状态和在线商品不能跨平台/门店复用。
@@ -74,7 +74,7 @@ Headers：`Idempotency-Key` 必填，页头平台由 header 指定，body 为空
} }
```
`variants` 每项同时返回通用 SKU、合并后实物/包装规格、当前平台 listing 摘要（含 `offer_id`、价格、首次导入状态、最近脱敏失败原因）、SKU 覆盖的 `tags` / `description` 及已选媒体。SKU 的 `tags: []`、`description: null` 分别表示继承 SPU 主题标签、产品描述；动态属性 schema 由第 3 节的独立接口按当前类目读取。候选和已选媒体只含 `asset_id`、尺寸、MIME、来源角色与短时预览 URL；不含 `object_key` 或永久 URL。
`variants` 每项同时返回通用 SKU、合并后实物/包装规格、当前平台 listing 摘要（含 `offer_id`、价格、首次导入状态、最近脱敏失败原因）、SKU 覆盖的 `tags` / `description` 及已选媒体。AI 填报落地时新增 SKU 发布标题 `title`；`title: null`、`tags: []`、`description: null` 分别表示继承 SPU 当前平台的标题、主题标签、产品描述。读取模型还须返回逐 SKU 三项有效文案及中俄对照来源（`inherit_spu` / `override`），以支持编辑页和发布适配器使用同一继承结果；`display_name` 不能作为发布标题。动态属性 schema 由第 3 节的独立接口按当前类目读取。候选和已选媒体只含 `asset_id`、尺寸、MIME、来源角色与短时预览 URL；不含 `object_key` 或永久 URL。
`default_package_spec` 是 SPU 的存储事实，`variants[].package_spec` 仅保存该 SKU 的覆盖值；`effective_package_spec` 按“SKU 覆盖值优先、SPU 默认值回退”解析。Ozon 发布适配器在创建 job 时才将每个目标 SKU 的有效值物化为独立 `items[]`：`length_mm → depth`、`width_mm → width`、`height_mm → height`、`shipping_weight_g → weight`，并固定带上 `dimension_unit: "mm"` 与 `weight_unit: "g"`。不得为了 payload 预先将 SPU 默认值复制到所有 SKU 草稿。商品净重/尺寸不是这组固定物流字段；它们的 SPU/SKU 展示归属由当前 Ozon schema 的 `is_aspect` 决定。
@@ -82,7 +82,7 @@ Headers：`Idempotency-Key` 必填，页头平台由 header 指定，body 为空
`captured_category_match` 仅对 Ozon 来源返回自动类目判定结果。服务端只使用公开详情页的**一级**面包屑和结构化 `Type_0` 商品类型，在当前平台目录的活动可发布叶子中精确匹配；公开页后二、三级导航不参与判定。`matched` 时服务端已自动写入 `source_capture`；`ambiguous` 时前端展示 `candidates` 的完整 Atlas 路径，用户确认后按普通手选类目保存为 `manual`；`unmatched`、`unavailable` 均不得自动选择。
`ai_input` 是后续 AI 任务的服务端输入视图：由上述有效 `source_material`、父商品默认实物/包装规格，以及每个 SKU 合并继承后的有效规格与规格轴组成。
`ai_input` 是后续 AI 任务的服务端输入视图：由上述有效 `source_material`、父商品默认实物/包装规格，以及每个 SKU 的稳定 ID、来源/展示名称、合并继承后的有效规格与规格轴组成。统一 AI 填报还需读取已保存的 SPU 与逐 SKU 文案及其覆盖状态，避免覆盖手填值；来源 SKU 仅作证据，不直接作为目标货号。
## 2. 原子保存草稿与 SKU 规则
@@ -128,7 +128,8 @@ Headers：`If-Match: "{product_revision}:{profile_revision}"`、`Idempotency-Key
- `target_store_id` 只能是当前工作空间、当前平台的活动店铺。变更目标店铺只更新**尚未导入** listing 的将来发布目标；`imported` listing 永远保留其首次导入时的店铺快照。
- 类目变化后不匹配的旧属性作为未映射草稿返回 warnings，不能自动进入发布 payload。属性由平台 schema 校验 `type`、必填、字典、多值/复杂属性和 `is_aspect`；客户端不能用任意 JSON 绕过。
- `media_asset_ids` 是本 SKU 当前平台的最终选图顺序；首期最多 15 张。格式只允许 JPG/PNG/WebP，单文件最多 20 MB，边长超过 10,000 px 拒绝，短边小于 700 px 不得作为首图并给出警告。第一张是主图。
- `common.model` 是用户填写的商品型号；采集时允许为空，但每次首次上架前必须非空。`offer_id` 是用户填写的目标平台卖家货号；采集时不得从 `source_sku` 自动生成或填入。草稿可为空，但每个待首次上架 SKU 的 `offer_id` 必须非空且在同一店铺/平台唯一。
- `common.model` 是用户手填或主动 AI 填报的商品型号；采集时允许为空，但每次首次上架前必须非空。`offer_id` 是用户手填或主动 AI 填报的目标平台卖家货号；采集入箱时不填值，生成时不直接复用 `source_sku`。草稿可为空，但每个待首次上架 SKU 的 `offer_id` 必须非空且在同一店铺/平台唯一。AI 填报接口和回填规则见[方案](../product/ai-autofill-plan.md)。
- `common.source_title` 在编辑页显示为“中文商品名”；`profile.title` 显示为“俄文发布标题”，页面保存时必填。为允许先保存采集草稿再使用 AI 填报，API 草稿契约仍接受空标题；发布就绪校验在 `profile.title` 为空时返回 `PUBLISH_TITLE_REQUIRED`。SKU 发布标题 `variants[].title` 为 `null` 时继承 `profile.title`，不回退到 `display_name`；现有 SKU `tags=[]`、`description=null` 保持继承语义。标题、标签、描述分别独立覆盖。中俄对照按 SPU/SKU 与字段随 `editor-draft` 原子保存；SKU 继承项直接引用 SPU 对照，手工俄文覆盖但无匹配中文时标为对照待更新。发布适配器使用 SKU 有效文案仍是后续工作。
成功返回新 `product.revision`、`profile.revision`、创建的 SKU ID/`client_key` 映射和 warnings。任一字段、属性或媒体无效时返回 `422` 且不部分保存；版本冲突返回 `409 VERSION_CONFLICT`，客户端应重新读取编辑快照。
@@ -174,7 +175,7 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": "
`GET /api/product-platform-profiles/{profile_id}/validation`
返回 profile 与每个未删除 SKU 的本地首次上架校验：标题、型号、品牌、类目/属性、目标店铺、用户填写的 offer ID、确认的包装规格、已确认定价快照、图片、格式/数量及平台特有规则。已导入 SKU 单独标记 `not_publishable_again`，而不是当作校验失败。
返回 profile 与每个未删除 SKU 的本地首次上架校验：每个待发布 SKU 的有效标题（SKU 覆盖优先、SPU 默认回退）、型号、品牌、类目/属性、目标店铺、用户填写的 offer ID、确认的包装规格、已确认定价快照、图片、格式/数量及平台特有规则。SKU 覆盖标题或 SPU 回退标题均为空时，该 SKU 不可发布；已导入 SKU 单独标记 `not_publishable_again`，而不是当作校验失败。SKU 标题生效前此处仍按现有 SPU 标题校验。
响应 `data`：
@@ -262,26 +263,19 @@ Headers：`Idempotency-Key` 必填。Body：
`GET /api/media-derivatives/{derivative_id}` 返回任务状态、脱敏错误及成功时的输出素材短时预览；不能泄露 `object_key`。
## 6. AI 任务与人工应用
## 6. AI 填报任务与页面回填
所有 AI 接口都只创建任务并返回 `202` + operation/`ai_task_id`，绝不直接改写草稿或发布数据。
AI 填报接口只创建异步任务并返回 `202` + `ai_task_id`，不直接改写已保存草稿或发布数据。任务完成后，编辑页自动把校验合格的字段回填到**未保存表单**，再由用户使用现有 `editor-draft` 保存。详细字段规则、冲突策略与中文对照存储见[商品 AI 填报方案](../product/ai-autofill-plan.md)。
创建 AI 任务前，前端必须先保存当前编辑草稿。服务端从已持久化的 `ai_input` 组装输入，不接收客户端自行拼装的规格：文案和类目任务可读取全部 SKU 的规格摘要；套图和尺寸图任务只读取目标 SKU 的 `effective_physical_spec` / `effective_package_spec`。因此 AI 使用的是用户在编辑页保存后的包装规格与商品规格，而不是采集载荷中的尺寸猜测值。
创建 AI 任务前，前端必须先保存当前编辑草稿。服务端从已持久化的 `ai_input` 组装输入，不接收客户端自行拼装的规格。填报任务读取全部 SKU 的规格摘要，并固化商品、profile、采集和类目目录版本；套图和尺寸图任务只读取目标 SKU 的 `effective_physical_spec` / `effective_package_spec`。因此 AI 使用的是用户在编辑页保存后的资料，而不是浏览器临时拼接的采集载荷。
| 接口 | body 核心字段 | 成功结果 |
|---|---|---|
| `POST /api/product-platform-profiles/{profile_id}/ai/category-suggestions` | 可选 `hint` | 读取采集证据和当前平台类目树，创建类目候选任务。Ozon 来源默认不自动调用，但用户可主动调用。 |
| `POST /api/product-platform-profiles/{profile_id}/ai/copy` | `fields: [title,tags,description]`、可选语言 | 创建当前平台文案候选。首期不生成富内容。 |
| `POST /api/product-platform-profiles/{profile_id}/ai/autofills` | 可选 `hint` 与策略开关；Header 必填 `Idempotency-Key` | 一次创建类目、型号、未导入 SKU 货号、可证包装规格及中俄文案的填报任务。Ozon 来源先运行确定性类目匹配；其他来源使用受限类目树候选。 |
| `POST /api/product-platform-profiles/{profile_id}/ai/suite-plans` | `variant_ids` 必填、`prompt` 可选 | 每个目标 SKU 明确绑定，创建套图规划/生成任务。 |
| `POST /api/product-platform-profiles/{profile_id}/variants/{variant_id}/ai/dimension-images` | 可选样式 | 固化该 SKU 合并后的**实物**规格快照；实物规格缺失/待确认返回 `422`。 |
`GET /api/product-ai-tasks/{ai_task_id}` 返回状态、模型/输入摘要、候选输出或脱敏错误。
`GET /api/product-ai-tasks/{ai_task_id}/category-suggestions` 返回候选类目、置信度、依据、rank。
`POST /api/product-ai-tasks/{ai_task_id}/category-suggestions/{suggestion_id}/apply`
Headers：`If-Match`、`Idempotency-Key` 必填。用户确认后才将候选写入 profile 的类目/类型并标记 `category_source=ai_suggestion`；随后要求重新读取 schema、审查未映射属性。文案/图片 AI 输出同样由用户在下一次 `editor-draft` 中明确选择并保存。
`GET /api/product-ai-tasks/{ai_task_id}` 返回任务状态、输入版本、脱敏结果或错误；全局填报成功时返回类目或候选、型号、逐 SKU 货号、可证包装建议及 SPU 中俄文案，不生成 SKU 文案。单 SKU 文案由 `POST /api/product-platform-profiles/{profile_id}/variants/{variant_id}/ai/copy` 单独创建任务，在弹窗预览并由用户应用。Ozon 动态类目属性不属于当前 AI 填报范围，仍通过类目确认后加载的 schema 由用户填写。歧义类目仍需用户选择。中文对照与俄文在下一次 `editor-draft` 中一同保存，读取编辑上下文时一同返回。
## 7. 部分 SKU 首次上架
@@ -297,7 +291,7 @@ Headers：`Idempotency-Key` 必填。Body：
服务端在创建任务前重新运行第 3 节校验。只允许当前 profile 中状态为 `not_listed` 或 `failed` 的未删除 SKU；`submitting` 返回 `409 SKU_IMPORT_IN_PROGRESS`，`imported` 返回 `422 SKU_ALREADY_IMPORTED`，不得重新提交或把编辑草稿当平台更新。
校验通过后在同一事务创建 `product_publish_job` 和每个 SKU 的 `product_publish_job_item`，固化 profile、目标店铺、类目/属性、价格快照、图片访问 URL、offer ID、该 SKU 的有效包装规格和平台适配请求，再投递 Worker。适配请求中的每个 Ozon `items[]` 必须包含该 SKU 独立解析出的 `depth`、`width`、`height`、`dimension_unit`、`weight`、`weight_unit`，不得省略或传 0。返回 `202`：
校验通过后在同一事务创建 `product_publish_job` 和每个 SKU 的 `product_publish_job_item`，固化 profile、目标店铺、类目/属性、价格快照、图片访问 URL、offer ID、该 SKU 的有效标题／标签／描述、有效包装规格和平台适配请求，再投递 Worker。三个文案字段都按「SKU 覆盖优先，SPU 默认回退」逐字段解析，中文对照不进入 Ozon 请求。适配请求中的每个 Ozon `items[]` 必须包含该 SKU 独立解析出的 `depth`、`width`、`height`、`dimension_unit`、`weight`、`weight_unit`，不得省略或传 0。返回 `202`：
```json
{ "data": { "publish_job": { "id": "uuid", "status": "queued", "store_id": "uuid", "item_count": 2 } } }