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

feat(edit): 编辑页上报ozon 开发

Browse Source
This commit is contained in:
R524809
2026-09-30 15:57:54 +08:00
parent 0a303414d8
commit 45871584b3
48 changed files with 3700 additions and 887 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/product-editor-and-publishing.md
+15 -13
View File
@@ -45,7 +45,7 @@ Headers：`Idempotency-Key` 必填，页头平台由 header 指定，body 为空
"profile": {
"id": "uuid", "revision": 8, "platform_id": "uuid", "market_code": "RU", "fulfillment": "rfbs",
"target_store": { "id": "uuid", "name": "Ozon 主店", "currency_code": "RUB" },
"title": "俄语标题", "description": null, "tags": [],
"title": "俄语标题", "title_mode": "common", "description": null, "tags": [],
"category": { "id": "uuid", "platform_type_id": "123", "source": "source_capture", "name": "收纳箱", "path": "家居 › 收纳 › 收纳箱" },
"listing_summary": { "status": "partially_listed", "detail": "1 个 SKU 已导入" }
},
@@ -120,7 +120,7 @@ Headers：`If-Match: "{product_revision}:{profile_revision}"`、`Idempotency-Key
"default_physical_spec": { "length_mm": "100", "width_mm": "50", "height_mm": "20", "net_weight_g": "300", "status": "confirmed" },
"default_package_spec": { "length_mm": "120", "width_mm": "60", "height_mm": "30", "shipping_weight_g": "400", "status": "confirmed" },
"package_weight_mode": "common", "package_dimensions_mode": "common" },
"profile": { "target_store_id": "uuid", "fulfillment": "rfbs", "title": "Название", "description": "…", "tags": ["tag"],
"profile": { "target_store_id": "uuid", "fulfillment": "rfbs", "title": "Название", "title_mode": "common", "description": "…", "tags": ["tag"],
"platform_product_category_id": "uuid", "category_source": "manual" },
"variants": [{
"id": "uuid-or-null", "client_key": "new-row-key", "copy_from_variant_id": null, "display_name": "黑色 / M", "source_sku": null,
@@ -149,7 +149,7 @@ Headers：`If-Match: "{product_revision}:{profile_revision}"`、`Idempotency-Key
- 类目变化后不匹配的旧属性作为未映射草稿返回 warnings，不能自动进入发布 payload。属性由平台 schema 校验 `type`、必填、字典、多值/复杂属性和 `is_aspect`；客户端不能用任意 JSON 绕过。
- `media_asset_ids` 是本 SKU 当前平台的最终选图顺序；最多 30 张。格式只允许 JPG/PNG/WebP，单文件最多 20 MB，边长超过 10,000 px 拒绝，短边小于 700 px 不得作为首图并给出警告。第一张是主图。已完成的 `product_image` 上传素材和网络导入素材可供同工作空间的 SKU 选择；当前商品成功的水印与 3:4 处理结果也可选择。采集图片仍须先转存，且来源变体须匹配。
- `common.model` 是用户手填或主动 AI 填报的商品型号；采集时允许为空，但每次首次上架前必须非空。`offer_id` 是用户手填或主动 AI 填报的目标平台卖家货号；采集入箱时不填值，生成时不直接复用 `source_sku`。草稿可为空，但每个待首次上架 SKU 的 `offer_id` 必须非空且在同一店铺/平台唯一。AI 填报接口和回填规则见[方案](../product/ai-autofill-plan.md)。
- `common.source_title` 在编辑页显示为“中文商品名”；`profile.title` 显示为“俄文发布标题”。编辑页保存草稿时允许中文商品名、俄文发布标题、型号、品牌、产品类目及类目必填属性留空，必填标记只提示首次上架所需资料；首次上架预检统一检查缺失项，`profile.title` 为空时返回 `PUBLISH_TITLE_REQUIRED`。草稿仍须携带有效的 `target_store_id` 作为店铺上下文，并遵守已填写字段的格式和长度约束。SKU 发布标题 `variants[].title` 为 `null` 时继承 `profile.title`，不回退到 `display_name`；现有 SKU `tags=[]`、`description=null` 保持继承语义。标题、标签、描述分别独立覆盖。中俄对照按 SPU/SKU 与字段随 `editor-draft` 原子保存；SKU 继承项直接引用 SPU 对照，手工俄文覆盖但无匹配中文时标为对照待更新。发布适配器使用 SKU 有效文案仍是后续工作。
- `common.source_title` 在编辑页显示为“中文商品名”；`profile.title` 显示为“俄文标题”。`profile.title_mode` 为 `common` / `variant`，编辑快照必须返回当前模式，保存草稿时可传入；旧客户端省略时保留原模式，新商品默认为 `common`。切到 `variant` 时清空并禁用 SPU 俄文标题，在各 SKU 展示标题输入；切回 `common` 时经确认清空所有 SKU 俄文标题，恢复 SPU 输入。两种模式均允许空白草稿；首次上架预检在 `common` 模式检查 `profile.title`，在 `variant` 模式逐个检查待发布 SKU 的 `variants[].title`，缺失时返回 `PUBLISH_TITLE_REQUIRED`。草稿仍须携带有效的 `target_store_id` 作为店铺上下文，并遵守已填写字段的格式和长度约束。SKU 标题 `variants[].title` 为 `null` 时在旧覆盖语义下继承 `profile.title`，不回退到 `display_name`；新版逐 SKU 模式不允许发布时依赖该继承。现有 SKU `tags=[]`、`description=null` 保持继承语义。标题、标签、描述分别独立覆盖。中俄对照按 SPU/SKU 与字段随 `editor-draft` 原子保存；SKU 继承项直接引用 SPU 对照，手工俄文覆盖但无匹配中文时标为对照待更新。发布适配器使用 SKU 有效文案仍是后续工作。
成功返回新 `product.revision`、`profile.revision`、创建的 SKU ID/`client_key` 映射和 warnings。任一字段、属性或媒体无效时返回 `422` 且不部分保存；版本冲突返回 `409 VERSION_CONFLICT`，客户端应重新读取编辑快照。
@@ -236,7 +236,7 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": "
`POST /api/product-platform-profiles/{profile_id}/publish-preflights`
Body：`{ "variant_ids": ["uuid", "uuid"] }`，最多 100 个且不能重复。该接口是创建真正发布 job 之前的可重算预检，不固化商品发布快照；平台目录任务按资源 `scope_key` 幂等合并，因此重复预检不会并发重复请求 Ozon。
Body：`{ "variant_ids": ["uuid", "uuid"] }`，最多 50 个且不能重复。该接口是创建真正发布 job 之前的可重算预检，不固化商品发布快照；平台目录任务按资源 `scope_key` 幂等合并，因此重复预检不会并发重复请求 Ozon。
预检只接受当前 profile 下 `not_listed` / `failed` 的未删除 SKU。`submitting` 返回 `409 SKU_IMPORT_IN_PROGRESS`，`imported` 返回 `422 SKU_ALREADY_IMPORTED`，不属于当前商品或已删除返回 `422 PUBLISH_VARIANTS_INVALID`。
@@ -293,31 +293,33 @@ AI 填报接口只创建异步任务并返回 `202` + `ai_task_id`，不直接
`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 首次上架
## 7. SKU 首次上架（2026-09-30 实施修订）
> 当前实现到上述 `publish-preflights`。以下 `publish-jobs`、Ozon `/v3/product/import` 提交和结果轮询仍是冻结契约，尚未开发；不得把预检 `ready` 当成已经提交或发布成功。
底部提供「上架至 OZON」和「部分上架」。前者选择全部 `not_listed` / `failed` 活动 SKU，列出已导入或正在提交的跳过原因；后者由用户选择相同资格的 SKU。一次 1–50 个，超过时提示分批，不自动拆批。先保存草稿，再对相同选择集合预检，用户确认后创建任务。
`POST /api/product-platform-profiles/{profile_id}/publish-jobs`
Headers：`Idempotency-Key` 必填。Body：
Headers：`X-Atlas-Platform-Id`、`Idempotency-Key`、`If-Match: "product_revision:profile_revision"` 必填。Body：
```json
{ "variant_ids": ["uuid", "uuid"] }
```
服务端在创建任务前重新运行第 3 节校验。只允许当前 profile 中状态为 `not_listed` 或 `failed` 的未删除 SKU；`submitting` 返回 `409 SKU_IMPORT_IN_PROGRESS`，`imported` 返回 `422 SKU_ALREADY_IMPORTED`，不得重新提交或把编辑草稿当平台更新。
创建事务锁定商品、profile 和 listing，重新校验版本、活动店铺、当前类目、仍可用的 schema / 实际引用字典和选中 SKU 的字段。无需强制刷新整棵目录；必须读取当前有效类目，过期 schema / 字典通过预检刷新，创建时仍过期则阻断。返回 `409 VERSION_CONFLICT`、`409 SKU_IMPORT_IN_PROGRESS`、`422 SKU_ALREADY_IMPORTED`、`422 PUBLISH_VALIDATION_FAILED`（逐字段 details）、`422 PUBLISH_VARIANTS_INVALID`。`OZON_PUBLISH_ENABLED` 在开发/测试默认允许，生产默认关闭，真实 VAT / 图片验收后部署显式开启；关闭时返回 `503 OZON_PUBLISH_DISABLED`。
校验通过后在同一事务创建 `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`：
同一事务创建 `product_publish_jobs` / `product_publish_job_items`、将 listing 置为 `submitting`，写 Outbox（只含 job ID）。冻结商品/profile 版本、店铺、货号、Ozon 类目和属性、十进制价格、逐 SKU 标题/标签/描述、有效包装规格、素材 ID / checksum / 对象身份；签名 URL 不持久化。标题按 `title_mode` 选择，标签/描述按 SKU 覆盖回退。货号最多 50 字符，发布标题最多 500 字符，每 SKU 1–30 张图。首期仅 rFBS，不传 SPU 共用条码、库存、仓库、顶层 description、视频或富内容；中国主体跨境 rFBS 首期省略 `vat`，实际导入与商品信息税率核对后再决定。
```json
{ "data": { "publish_job": { "id": "uuid", "status": "queued", "store_id": "uuid", "item_count": 2 } } }
{ "data": { "publish_job": { "id": "uuid", "profile_id": "uuid", "store_id": "uuid", "status": "queued", "item_count": 2, "created_at": "ISO8601", "completed_at": null, "items": [] } } }
```
首期 Ozon `/v3/product/import` 不传仓库或库存。Worker 按 SKU 保存提交、轮询、成功/失败和平台原因；成功 SKU 状态为 `imported` 后不能从采集箱再次上架。SPU 的未上架/已部分上架/已上架由当前平台未删除 SKU 汇总，采集箱记录始终保留。
`GET /api/product-publish-jobs/{publish_job_id}` 返回 `{data: ProductPublishJob}`；必须传平台上下文，仅可访问当前工作空间和平台。`GET /api/product-platform-profiles/{profile_id}/publish-jobs` 返回 `{data: ProductPublishJob[]}`，最近 10 次任务，供页面刷新恢复。实际 `items` 含 id、variant_id、display_name、offer_id、status、platform_product_id、errors（code/field/message），不返回发布快照、签名 URL、密钥。job 状态为 `queued/running/succeeded/partially_succeeded/failed/reconciling`；item 状态为 `queued/submitting/polling/imported/failed/skipped/reconciling`。`reconciling` 表示提交结果不确定，listing 保持 `submitting`，禁止再次导入。202/任务 ID 仅表示受理。
`GET /api/product-publish-jobs/{publish_job_id}`
Worker 提交前查询远端货号；已存在则标 `skipped` 并保留原因，不能调用导入更新它。每批最多 50 个 SKU，提交前生成七牛独立 HTTPS 私有签名图地址（有效期可配置，WebP 转 JPEG）；来源与派生对象身份固定，地址仅在内存使用。导入请求的 task ID 持久化后通过延迟 Outbox 轮询，逐项处理 imported/failed/skipped。提交前预写 `submitting`：如果超时、5xx 或响应丢失，下次仅按货号对账，不盲目再次导入；无法确认则保持 reconciling。明确 429 可按 Retry-After 延迟再提交。读请求失败可以重试。平台 errors 必须脱敏，不得包含签名 URL 或请求体。
返回 job、每个 SKU item 的 `queued/submitting/polling/imported/failed/skipped`、Ozon task/product ID、时间和可展示的脱敏错误。发布失败不删除草稿或报价；用户修正未导入 SKU 后可以创建新的首次上架任务。在线商品镜像由另一个同步模块维护，不能以此 job 的状态替代 Ozon 当前 `visible`、库存或审核事实。
导入成功锁定历史货号/product ID 与商品型号；其他草稿属性可修改，不隐式更新平台。存在提交中 SKU 时禁止删除该 SKU、改型号或变更目标店铺。任一 SKU 已导入后型号不可修改。沿用现有草稿换店行为：没有正在提交的 SKU 时可调整目标店铺，已导入 SKU 保留原店铺和导入身份，仍不能重复上架。失败保留草稿/报价，可修复并新建任务；任务成功不代表审核通过或有库存，在线商品事实仍由独立同步维护。
生产验收：同类中国主体跨境 rFBS 店铺省略 VAT 的真实导入及 `/v3/product/info/list.vat` 结果、七牛域名/证书/签名期/延迟抓取和 WebP 派生图。不能仅以模拟平台测试宣称已经通过生产验收。
## 8. 已替代的旧草案
docs/integrations/ozon-seller-api/04-product-import.md
+56 -602
View File
@@ -1,619 +1,73 @@
# 商品导入（创建/更新）API
# Ozon 商品导入 API（2026-09-30 核对）
> 官方文档：https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_ImportProductsV3
官方：[创建或更新商品](https://docs.ozon.ru/api/seller/en/#operation/ProductAPI_ImportProductsV3)、[导入状态](https://docs.ozon.ru/api/seller/en/#operation/ProductAPI_GetImportProductsInfo)、[商品信息](https://docs.ozon.ru/api/seller/en/#operation/ProductAPI_GetProductInfoList)。Atlas 的产品流程、字段来源和错误契约以 [商品编辑与首次上架](../../api/product-editor-and-publishing.md) 为准。
---
## 创建或更新商品
## 接口信息
`POST /v3/product/import`，鉴权 Header 为 `Client-Id` / `Api-Key`。Ozon 每批最多 100 个 item，Atlas 首期收紧为最多 50 个 SKU。此接口也会更新已存在的货号，不能依赖“重复货号必定返回 409”。Atlas 在提交前查询当前店铺货号，存在时跳过；提交结果不确定时先对账，不能直接重发。
| 项 | 值 |
```json
{
"items": [{
"offer_id": "ATLAS-THERMOS-001",
"name": "Термокружка из нержавеющей стали 500 мл",
"description_category_id": 17033876,
"type_id": 97114,
"price": "2990.00",
"old_price": "3490.00",
"currency_code": "RUB",
"depth": 80,
"width": 80,
"height": 200,
"dimension_unit": "mm",
"weight": 320,
"weight_unit": "g",
"images": ["https://images.example.test/publishing/photo.jpg"],
"attributes": [{"complex_id": 0, "id": 9048, "values": [{"value": "ATLAS-THERMOS"}]}]
}]
}
```
示例类目、类型和属性必须替换为目标类目当前有效目录，不可直接作为真实商品输入。
| 字段 | 当前约束 / Atlas 首期处理 |
|---|---|
| 方法 | POST |
| 路径 | `/v3/product/import` |
| 鉴权 | 需要 `Client-Id` + `Api-Key` |
| 用途 | **创建或更新商品**（Ozon 核心接口） |
| 异步 | ✅ 返回 `task_id`，需轮询 `/v1/product/import/info` 获取最终状态 |
| `offer_id` | 最多 50 字符；每个 SKU 独立货号，当前店铺唯一 |
| `name` | 最多 500 字符；按已保存的标题模式选择通用或 SKU 标题 |
| `description_category_id` / `type_id` | 当前有效类目、类型数值 ID |
| `price` / `old_price` | 十进制字符串；售价大于零，划线价大于售价时才传 |
| `currency_code` | 与目标店铺实际币种一致 |
| `vat` | 官方俄/英文 OpenAPI 可选，中文版列为必填，存在差异；`0` 表示不征收 VAT，其他列出的值为 `0.05`、`0.07`、`0.1`、`0.2`、`0.22`。Atlas 中国主体跨境 rFBS 首期省略，真实测试后确认，不设置默认税率 |
| 包装规格 | 正整数 mm/g；每个 SKU 合并通用默认值与自己的覆盖值，不传商品本体规格 |
| `images` | JPG/PNG 公网链接，最多 30 张，第一张主图；若额外传 `primary_image`，则 images 最多 29 张。Atlas 首期不另传 `primary_image` |
| `attributes` | 按当前类目定义拼装；字典值用官方 ID 和文本，SKU aspect 属性独立解析。品牌、型号、标签和描述仅映射当前类目有效的固定属性 |
| 商品描述 | 不在 item 顶层传 `description`，应通过描述属性（例如当前类目可用时的 4191）填写 |
| 条码 / 库存 / 仓库 | rFBS 首期不传；不将 SPU 共用条码复制到多个 SKU |
| 视频、富内容、360 图 | 首期不发布 |
---
返回 `{"result":{"task_id":123456789}}` 只表示受理，商品导入仍需查询任务状态。
## 1. 请求体结构
## 查询导入结果
### 完整示例
`POST /v1/product/import/info` 请求 `{"task_id":123456789}`，返回 `result.items[]`，每项含 `offer_id`、`product_id`、`status`、`errors`。
```json
{
"items": [
{
"offer_id": "MY-THERMOS-001",
"name": "Термокружка Thermos из нержавеющей стали 500 мл",
"description": "Термокружка из высококачественной нержавеющей стали. Сохраняет температуру до 6 часов.",
"description_category_id": 17033876,
"type_id": 97114,
"price": "2990",
"old_price": "3490",
"currency_code": "RUB",
"vat": "0",
"depth": 80,
"width": 80,
"height": 200,
"dimension_unit": "mm",
"weight": 320,
"weight_unit": "g",
"images": [
"https://cdn.example.com/thermos-main-1.jpg",
"https://cdn.example.com/thermos-main-2.jpg"
],
"primary_image": "",
"images360": [],
"color_image": "",
"barcode": "",
"attributes": [
{
"complex_id": 0,
"id": 85,
"values": [
{
"dictionary_value_id": 971082156,
"value": "Thermos"
}
]
},
{
"complex_id": 0,
"id": 8505,
"values": [
{
"value": "Нержавеющая сталь"
}
]
}
],
"complex_attributes": []
}
]
}
```
---
## 2. 字段说明
### 基本信息
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **offer_id** | string | ✅ 是 | **自己的货号**（唯一标识，用于更新）。最长 255 字符 |
| **name** | string | ✅ 是 | 商品名称。最长 500 字符 |
| **description** | string | ✅ 是 | 商品描述。最长 5000 字符，支持 HTML 标签 |
| **description_category_id** | integer | ✅ 是 | 类目 ID（从类目树获取） |
| **type_id** | integer | ✅ 是 | 商品类型 ID（从类目树获取） |
### 价格
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **price** | string | ✅ 是 | 销售价（字符串格式，如 `"2990"` = 2990 卢布） |
| old_price | string | 可选 | 划线价（原价），用于展示折扣 |
| **currency_code** | string | ✅ 是 | 币种，通常 `"RUB"`（卢布）。也可 `"CNY"` 等 |
| **vat** | string | ✅ 是 | 增值税率：`"0"` / `"0.1"` / `"0.2"`。俄罗斯默认 `"0"` |
### 尺寸与重量
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **depth** | number | ✅ 是 | 长度（包装尺寸）。**不能为 0** |
| **width** | number | ✅ 是 | 宽度（包装尺寸）。**不能为 0** |
| **height** | number | ✅ 是 | 高度（包装尺寸）。**不能为 0** |
| **dimension_unit** | string | ✅ 是 | 尺寸单位：`"mm"` / `"cm"` |
| **weight** | number | ✅ 是 | 重量（包装重量）。**不能为 0** |
| **weight_unit** | string | ✅ 是 | 重量单位：`"g"` / `"kg"` |
⚠️ **硬约束**：尺寸和重量必须 **> 0**，否则 API 返回 400 错误。
### 图片
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **images** | array | ✅ 是 | **主图数组**（最多 15 张）。顺序即展示顺序，第一张为主图 |
| primary_image | string | 可选 | 主图（单独指定）。若使用则 `images` 最多 14 张 |
| images360 | array | 可选 | 360° 图片数组 |
| color_image | string | 可选 | 营销色图（部分类目支持） |
⚠️ **硬约束**：
- 图片 URL 必须是 **https 公网直链**（http 会被拒绝）
- 图片需可访问（Ozon 服务器会主动拉取）
- 建议尺寸：≥ 700×700 px，白底，主体占画面 80%+
### 属性
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **attributes** | array | ✅ 是 | 商品属性数组（从类目属性获取） |
| attributes[].complex_id | integer | ✅ 是 | 复杂属性 ID，通常填 `0` |
| attributes[].id | integer | ✅ 是 | 属性 ID |
| attributes[].values | array | ✅ 是 | 属性值数组 |
| values[].dictionary_value_id | integer | 条件 | 字典值 ID（属性有字典时必填） |
| values[].value | string | ✅ 是 | 属性值文本 |
### 复杂属性
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| complex_attributes | array | 可选 | 复杂属性（视频、尺码表等） |
### 其他
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| barcode | string | 可选 | 条形码 |
| pdf_list | array | 可选 | PDF 文件 URL 列表 |
---
## 3. 响应
### 成功响应（200）
```json
{
"result": {
"task_id": 123456789
}
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | integer | **任务 ID**（用于轮询状态，见下节） |
⚠️ **此时商品尚未创建**，需轮询 `/v1/product/import/info` 获取最终结果。
---
## 4. 轮询任务状态
### 接口信息
| 项 | 值 |
| 状态 | 处理 |
|---|---|
| 方法 | POST |
| 路径 | `/v1/product/import/info` |
| 鉴权 | 需要 `Client-Id` + `Api-Key` |
| `pending` | 继续轮询，等待导入 |
| `imported` | 保存远端 product ID，确认该 SKU 已导入；不等于审核通过、前台可见或有库存 |
| `failed` | 保存脱敏错误，用户修正后可以新建首次发布任务 |
| `skipped` | 对账确认是否已有商品；不能仅凭 skipped 声称导入成功 |
### 请求
审核状态应从商品信息接口读取，不能将 `processing` / `moderation` 当成此导入任务的 item 状态。
```json
{
"task_id": 123456789
}
```
## 查询商品信息与对账
### 响应
`POST /v3/product/info/list` 可传 `offer_id` / `product_id` / `sku`。当前官方响应为**顶层 `items[]`**，不是 `result.items[]`；每个商品含 `id`、`offer_id`、`vat`、`statuses` 等字段。
```json
{
"result": {
"items": [
{
"offer_id": "MY-THERMOS-001",
"product_id": 987654321,
"status": "imported",
"errors": []
}
]
}
}
```
Atlas 用它检查远端货号、恢复提交结果和核对 VAT。任务受理后不得因 HTTP 超时就重新发 `/v3/product/import`。无法确认时保持“等待对账”，禁止当前 SKU 再次入队。
### 状态值
## 图片签名与上线验收
| status | 含义 | 处理 |
|---|---|---|
| **imported** | ✅ 导入成功 | 保存 `product_id`，标记商品为 `published` |
| **pending** | ⏳ 排队中 | 继续轮询（间隔 5s） |
| **processing** | ⏳ 处理中 | 继续轮询（间隔 5s） |
| **moderation** | ⏳ 审核中 | 继续轮询（间隔 30s，审核可能需几小时） |
| **failed** | ❌ 失败 | 读取 `errors` 数组，展示错误给用户 |
素材从 Atlas 正式对象存储交付；10 分钟页面预览 URL 不用于发布。Worker 校验素材 checksum，为本次发布复制固定对象，将 WebP 转 JPEG，并从七牛 HTTPS 下载域名签发独立有效期 URL。URL 及签名不写入数据库、Outbox 或日志。
### 错误结构
```json
{
"offer_id": "MY-THERMOS-001",
"product_id": 0,
"status": "failed",
"errors": [
{
"code": "INVALID_ATTRIBUTE",
"message": "Attribute 'Бренд' is required",
"field": "attributes"
}
]
}
```
---
## 5. 轮询策略
### 推荐策略
```python
import asyncio
async def wait_for_import(task_id: int, timeout=300):
"""轮询导入状态，最多等待 5 分钟"""
start = time.time()
interval = 5 # 初始间隔 5s
while time.time() - start < timeout:
resp = await ozon_client.get_import_info(task_id)
item = resp["result"]["items"][0]
status = item["status"]
if status == "imported":
return {"success": True, "product_id": item["product_id"]}
if status == "failed":
return {"success": False, "errors": item["errors"]}
if status == "moderation":
interval = 30 # 审核阶段降低频率
await asyncio.sleep(interval)
# 超时：不算失败，标记为"审核中"继续后台轮询
return {"success": None, "status": "timeout"}
```
### 后台轮询（推荐）
```python
# 用户提交发布后立即返回，后台协程轮询
# 状态变化时通知前端（WebSocket / 长轮询 / 前端定时刷新）
async def background_poll_task(task_id: int, product_id: str):
"""后台协程，轮询直到完成或失败"""
result = await wait_for_import(task_id, timeout=3600) # 最多 1 小时
# 更新数据库
await db.execute(
update(Product)
.where(Product.id == product_id)
.values(
stage="published" if result["success"] else "failed",
ozon_product_id=result.get("product_id"),
published_at=datetime.utcnow() if result["success"] else None
)
)
# 记录任务结果
await db.execute(
update(PublishTask)
.where(PublishTask.ozon_task_id == task_id)
.values(
status=result.get("status"),
errors=result.get("errors"),
completed_at=datetime.utcnow()
)
)
```
---
## 6. 创建 vs 更新
### 创建新商品
```json
{
"offer_id": "NEW-PRODUCT-001", // 全新 offer_id
// ... 其他字段
}
```
- 如果 `offer_id` 不存在 → 创建新商品
- 如果 `offer_id` 已存在 → 返回 409 冲突
### 更新已有商品
```json
{
"offer_id": "EXISTING-001", // 已存在的 offer_id
// ... 要更新的字段（可部分更新）
}
```
或使用 `product_id`：
```json
{
"product_id": 987654321, // Ozon 商品 ID
// ... 要更新的字段
}
```
⚠️ **注意**：
- 更新时，未传的字段**保持原值**（非清空）
- 图片数组传空 `[]` 会清空图片（需小心）
- 建议更新前先读取当前值（`/v3/product/info/list`）
---
## 7. 批量导入
单次请求最多 **100 个 item**：
```json
{
"items": [
{ "offer_id": "PROD-001", /* ... */ },
{ "offer_id": "PROD-002", /* ... */ },
// ... 最多 100 个
]
}
```
响应包含每个 item 的状态：
```json
{
"result": {
"items": [
{ "offer_id": "PROD-001", "status": "imported", "product_id": 111 },
{ "offer_id": "PROD-002", "status": "failed", "errors": [...] }
]
}
}
```
---
## 8. 常见错误
### 错误码速查
| code | message | 原因 | 解决 |
|---|---|---|---|
| `INVALID_PARAMETER` | 参数错误 | 必填字段缺失 / 格式错误 | 检查字段完整性 |
| `INVALID_ATTRIBUTE` | 属性错误 | 缺少必填属性 / 字典值不匹配 | 补全必填属性，校验字典值 |
| `INVALID_CATEGORY` | 类目错误 | `description_category_id` 不存在或已禁用 | 重新选择类目 |
| `INVALID_IMAGE` | 图片错误 | URL 不可访问 / 非 https / 格式不支持 | 检查图片 URL 有效性 |
| `OFFER_ID_DUPLICATE` | offer_id 重复 | 该 offer_id 已存在 | 换一个唯一 offer_id 或走更新 |
| `DIMENSION_REQUIRED` | 尺寸必填 | 尺寸/重量为 0 或缺失 | 填写正确尺寸重量 |
| `PRICE_INVALID` | 价格错误 | 价格 ≤ 0 或格式错误 | 检查价格字段 |
### 典型错误示例
#### 错误 1：尺寸为 0
```json
{
"errors": [
{
"code": "DIMENSION_REQUIRED",
"message": "Dimensions must be greater than 0",
"field": "weight"
}
]
}
```
**解决**：确保 `depth/width/height/weight` 都 > 0。
#### 错误 2：缺少必填属性
```json
{
"errors": [
{
"code": "INVALID_ATTRIBUTE",
"message": "Required attribute 'Бренд' (id=85) is missing",
"field": "attributes"
}
]
}
```
**解决**：补充缺失的必填属性。
#### 错误 3：图片 URL 不可访问
```json
{
"errors": [
{
"code": "INVALID_IMAGE",
"message": "Image URL is not accessible: https://...",
"field": "images[0]"
}
]
}
```
**解决**：
1. 检查 URL 是 https（非 http）
2. 检查 URL 公网可访问（Ozon 服务器需能拉取）
3. 检查图片格式（支持 jpg/png/webp）
---
## 9. 发布后操作
### 设置库存（必须）
商品导入成功后**不会自动上架**，需设置库存才能开售：
```http
POST /v2/products/stocks
```
```json
{
"stocks": [
{
"product_id": 987654321,
"offer_id": "MY-THERMOS-001",
"stock": 100,
"warehouse_id": 12345678
}
]
}
```
⚠️ 不设置库存 → 商品在后台但不可购买。
### 查询商品详情
```http
POST /v3/product/info/list
```
```json
{
"offer_id": ["MY-THERMOS-001"]
}
```
返回商品完整信息（含审核状态、图片、属性）。
---
## 10. 早期集成示例（当前未实现）
> 下方 `server/api/publish.py` 与前端组件来自早期 V2 方案，不存在于当前 NestJS/React 实现中，仅可帮助理解流程，不能作为联调契约。Atlas 目前只完成 `publish-preflights`；真正的发布 job、`/v3/product/import` 提交和结果轮询尚未实现。当前契约见[商品编辑与发布 API](../../api/product-editor-and-publishing.md)。
### 历史 API 示例
```python
# server/api/publish.py
@router.post("/products/{product_id}/publish")
async def publish_product(
product_id: str,
shop_id: str = Body(...),
db: AsyncSession = Depends(get_db)
):
# 1. 取商品数据
product = await get_product(db, product_id)
# 2. 校验必填项
validate_required_fields(product)
# 3. 组装 ImportProductsV3 请求体
item = build_import_item(product)
# 4. 调用 Ozon API
shop = await get_shop(db, shop_id)
resp = await ozon_client.import_products(
shop.client_id_dec,
shop.api_key_dec,
[item]
)
task_id = resp["result"]["task_id"]
# 5. 记录发布任务
task = PublishTask(
product_id=product_id,
shop_id=shop_id,
ozon_task_id=task_id,
status="pending",
request_payload=item
)
db.add(task)
await db.commit()
# 6. 启动后台轮询
asyncio.create_task(background_poll_task(task_id, product_id))
return {"task_id": task_id}
def build_import_item(product: Product) -> dict:
"""组装 ImportProductsV3 items[0]"""
return {
"offer_id": product.offer_id,
"name": product.name,
"description": product.description,
"description_category_id": product.description_category_id,
"type_id": product.type_id,
"price": str(product.price),
"old_price": str(product.old_price) if product.old_price else "",
"currency_code": product.currency_code,
"vat": product.vat,
"depth": product.depth,
"width": product.width,
"height": product.height,
"dimension_unit": product.dimension_unit,
"weight": product.weight,
"weight_unit": product.weight_unit,
"images": product.images, # 七牛 URL 数组
"primary_image": product.primary_image or "",
"images360": product.images360 or [],
"color_image": product.color_image or "",
"barcode": product.barcode or "",
"attributes": product.attributes or [],
"complex_attributes": product.complex_attributes or []
}
```
### 前端（待实现）
```tsx
// studio/src/pages/product/components/PublishPanel.tsx
import { Button, Select, message } from 'antd';
export function PublishPanel({ productId }) {
const [shops, setShops] = useState([]);
const [publishing, setPublishing] = useState(false);
const handlePublish = async (shopId) => {
setPublishing(true);
try {
const resp = await fetch(`/api/products/${productId}/publish`, {
method: 'POST',
body: JSON.stringify({ shop_id: shopId })
});
const data = await resp.json();
message.success('发布任务已提交，轮询中...');
// 轮询状态（或 WebSocket 推送）
pollPublishStatus(data.task_id);
} catch (err) {
message.error(`发布失败: ${err.message}`);
} finally {
setPublishing(false);
}
};
return (
<div>
<Select
placeholder="选择目标店铺"
options={shops.map(s => ({ label: s.name, value: s.id }))}
onChange={handlePublish}
/>
<Button
type="primary"
loading={publishing}
onClick={() => /* trigger select */}
>
发布到 Ozon
</Button>
</div>
);
}
```
---
## 相关文档
- [02-category-tree.md](./02-category-tree.md) —— 获取类目
- [03-category-attributes.md](./03-category-attributes.md) —— 获取属性
- [05-product-info.md](./05-product-info.md) —— 查询商品详情
- [09-stocks.md](./09-stocks.md) —— 设置库存（必须）
- [商品编辑与发布 API](../../api/product-editor-and-publishing.md) —— 当前 Atlas 预检与未来发布契约
- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md) —— 发布前属性/字典刷新边界
真实中国主体跨境 rFBS 店铺的 VAT 行为、七牛域名 / 证书 / 过期时间和 Ozon 延迟抓取仍须联调验收。生产默认关闭上架，验收后显式设置 `OZON_PUBLISH_ENABLED=true`。配置参见 `.env.example`。
docs/product/ozon-first-publish-review-plan.md
+118
View File
@@ -0,0 +1,118 @@
# 编辑页 Ozon 首次上架：字段对齐、开发方案与实施记录
> 2026-09-30：产品决策已确认，首期代码已实现；真实店铺 VAT 与七牛图片交付验收待完成。现行接口以 `docs/api/product-editor-and-publishing.md` 为准，下文保留字段研究与实施方案供追溯。
## 1. 目标和首期边界
编辑页底部将当前禁用的「选择 SKU 并首次上架」替换为两个入口：
| 入口 | 建议行为 |
|---|---|
| **上架至 OZON** | 只校验并提交当前平台、目标店铺下状态为 `not_listed` / `failed` 的活动 SKU；已成功导入的 SKU 保留原记录、不重复提交，并在确认摘要中逐项说明已跳过的 SKU。任一待提交 SKU 或商品级字段未通过预检，本次一个也不提交。 |
| **部分上架** | 打开 SKU 选择窗口，仅可选择当前商品下 `not_listed` / `failed` 的活动 SKU；至少选择 1 个，只校验并提交选中的 SKU。`submitting` 和 `imported` 展示状态、原因提示，但不可勾选。 |
这是**首次导入 Ozon 商品卡片**，不是更新已导入商品，也不包含库存设置。Ozon 的 `imported` 表示商品资料已导入；审核、前台可见性和可售库存需以在线商品同步与后续库存能力为准。按钮文案按需求使用“上架”，结果页须明确显示“已导入 / 待审核 / 不可售”等平台事实，不能把 `202` 或 Ozon `task_id` 当作上架成功。
首期沿用当前 Ozon `rFBS` 商品发布配置；`fbs`、`fbo`、`fbp` 的仓库、条码与库存规则另行验收。在当前首期中，不向 Ozon 提交仓库或库存。首期不发布视频、视频封面、富内容，也不借此入口修改已导入商品。
一次首次上架最多提交 **50 个 SKU**，包括“上架至 OZON”自动选出的待提交集合和“部分上架”手选集合；超过 50 个时先提示用户分批使用“部分上架”，不自动拆批或静默截取前 50 个。Ozon 接口本身允许的数量更高，但首期按本产品决策收紧。
## 2. 官方接口核对（2026-09-30）
本次直接核对 Ozon 官方 Seller API 页面及其 OpenAPI 2.1 定义：
1. [创建或更新商品 `POST /v3/product/import`](https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_ImportProductsV3)：一次最多 100 个 `items`；返回 `result.task_id`，仍需查询任务。它同时是**更新**接口，因此首次上架不能仅凭 HTTP 200 推断新建成功，也不能盲目重试不确定的提交。
2. [查询导入状态 `POST /v1/product/import/info`](https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_GetImportProductsInfo)：按 `task_id` 返回各 `offer_id` 的 `product_id`、`status`、`errors`。官方列出的 item 状态是 `pending`、`imported`、`failed`、`skipped`；`skipped` 不能直接等同首次导入成功。
3. [按标识符查询商品 `POST /v3/product/info/list`](https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_GetProductInfoList)：可按 `offer_id` / `product_id` / `sku` 查询，单次总计最多 1000 个；返回 `statuses.moderate_status` 等审核、验证和可见状态。用于提交前货号归属检查、超时后的对账及导入后的状态同步。
4. [类目属性 `POST /v1/description-category/attribute`](https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_GetAttributes) 与[类目树](https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_GetTree)：类目 / 类型及必填、SKU 维度、字典属性以平台当前目录为准。Atlas 已有平台级目录缓存和发布预检，发布任务继续复用它们。
5. [商品操作限额 `POST /v4/product/info/limit`](https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_GetUploadQuota)：按门店检查创建/更新额度；导入接口的 429 还可能带 `Item-Retry-After` 和 `Item-Rate-Limit-Remaining`，Worker 应尊重重试时间。
评审时提供的毛子 ERP 请求体顶层是 `product_id`、`form_data`、`is_online`，`form_data` 中含 `shop_id` 和 `skus`，整个请求体未出现 `vat`。它是 ERP 接收编辑表单的请求形状，不是 Ozon `/v3/product/import` 所需的顶层 `items[]` 形状；仅凭这一份请求，无法判断 ERP 服务端是否补上 VAT、调用了另一个 Ozon 接口，或采用了其他处理。
**VAT 文档存在版本冲突，不能再称为已确认必传**：同一 `v3ImportProductsRequestItem` 的 Ozon 官方 [俄文 OpenAPI](https://docs.ozon.ru/api/seller/swagger.json) 和[英文 OpenAPI](https://docs.ozon.ru/api/seller/en/swagger.json)的 `required` 均只有 `description_category_id`、`price`、`type_id`、`offer_id`，`vat` 是可选属性；[中文 OpenAPI](https://docs.ozon.ru/api/seller/zh/swagger.json)则将 `vat` 列为必填。这三份文档均标为 2.1，不能凭语言版本判断真实店铺校验结果。俄文与英文说明将 `vat: "0"` 定义为“该商品不征收 VAT”，并未声明“不传 `vat`”的默认行为；也未找到明确规定“中国主体、跨境 rFBS”一律应传哪个值的 Ozon 官方说明。[Ozon Global 跨境合同](https://global-help.ozon.com/contracts-for-sellers/dogovor/)区分 Ozon 服务费 VAT 与交易适用税款，也没有给出导入字段的固定税率。中国出口环节的增值税处理不能直接推导此商品字段的值。
**现有整理稿需要在评审后订正**：`docs/integrations/ozon-seller-api/04-product-import.md` 写了 `offer_id` 最长 255、图片最多 15、顶层 `description`、以及“重复货号必定 409”；官方当前导入定义分别是**最多 50 字符、最多 30 张图片、描述不在 item 顶层字段、同一导入接口同时承担创建和更新**。旧整理稿列出的 `processing`、`moderation` 也不是当前 `/v1/product/import/info` 的 item 状态；审核状态另从商品信息接口读取。按本次产品决策，**编辑草稿改为货号最多 50 字符、Ozon 发布标题最多 500 字符、每 SKU 最多 30 张图片**，与 Ozon 当前导入接口一致；来源商品标题等采集证据不因发布标题上限而改写。已有超长草稿需提示用户修正，不自动截断或静默改写。
## 3. Atlas → Ozon 字段映射
| Ozon `items[]` 字段 | Atlas 来源与适配 | 发布时校验 |
|---|---|---|
| `offer_id` | 当前目标店铺下该 SKU 的 `listing.offer_id`，原样作为卖家货号 | 草稿和 Ozon 当前接口均最多 50 字符；现存超长值在编辑页显示并要求用户主动修正，保存 / 上架均不自动截断。本店数据库唯一，并查询 Ozon 当前店铺同货号是否已存在。 |
| `name` | 通用模式取 SPU `profile.title`；按 SKU 设置模式取当前 SKU 标题 | 草稿与 Ozon 当前接口均最多 500 字符；俄文标题不可为空。SKU `display_name` 不作回退。 |
| `description_category_id`, `type_id` | 当前平台活动叶子类目缓存对应的 Ozon 数值 ID | 均有效；schema 和实际使用字典通过现有 `publish-preflights` 定向刷新。 |
| `price`, `old_price`, `currency_code` | SKU 已确认报价的售价 / 划线价；币种来自目标店铺 | 保留十进制字符串精度；`price > 0`；仅 `old_price > price` 时传 `old_price`；报价仍与当前采购、包装、店铺、类目和履约匹配，币种与店铺 Ozon 账户一致。 |
| `vat` | 当前模型缺字段；中、俄、英文官方 schema 对是否必传有冲突。对已确认的中国主体、跨境 rFBS 店铺，首期拟**省略字段**，不擅自填 `"0"` 或俄罗斯境内税率；若该店铺确有适用税率，以卖家或 Ozon 支持确认值为准。 | `"0"` 在俄/英文定义中是“不征收 VAT”，不是“省略”；省略后 Ozon 是否补默认值尚无官方结论。测试店铺须做一次真实导入，查询任务结果与 `/v3/product/info/list` 返回的 `vat`，确认可接受且结果符合店铺税务设置后再开放生产发布；若被拒绝或结果不符，暂停该店铺发布并由卖家确认税率，不自动重试成 `"0"`。 |
| `depth`, `width`, `height`, `dimension_unit`, `weight`, `weight_unit` | 每个 SKU 合并继承后的**包装**长宽高与物流重量；首期统一 mm/g | 均为已确认的正整数，不能拿商品本体尺寸或净重替代；每个 item 独立解析。 |
| `images` / `primary_image` | 当前 SKU 已保存的素材 ID 及顺序；首期用 `images` 首张作为主图，不另传 `primary_image` | 草稿最多 30 张，现有迁移 `031_sku_image_limit.sql` 已把数据库顺序上限扩至 30，与 Ozon 当前数量上限一致。发布时从正式素材生成 Ozon 可访问的公网 HTTPS JPG/PNG 地址；WebP 需生成 JPG/PNG 发布派生图或给出可定位的阻断项。 |
| `barcode` | 当前只有 SPU 通用条码 | rFBS 首期允许不传；不得把同一个通用条码复制给多个 SKU。需要按 SKU 条码或 FBP 发布时，先扩充数据模型和校验。 |
| `attributes[]` | 类目动态属性中已确认的通用值复制到本次各 SKU，`is_aspect=true` 的值只取当前 SKU；主要信息字段依固定 Ozon ID 映射 | `id` / `complex_id` 转数值；字典值以官方 ID 及缓存文本构成 `dictionary_value_id` / `value`，文本值构成 `value`。仅提交当前类目活动属性，强制项和最大值数沿用最新 schema。 |
| `complex_attributes` | 首期无视频或复杂富内容输入 | 无值时省略或空数组；不虚构。 |
现有固定属性绑定是品牌 `85`、型号 `9048`、商品类型 `8229`、标签 `23171`、富内容 `11254`、简介 `4191`。发布适配器应只在当前类目 schema 确认这些 ID 可用时映射：品牌、型号、有效的 SKU / SPU 标签与描述进入对应属性；`type_id` 已在顶层时不重复拼装 `8229`。这些 ID 目前来自 Atlas 的绑定实现；**在发布适配器编码前应以目标类目的实时属性响应验证值类型、字典约束与可用性**，不能仅靠旧示例。中文对照、中文商品名、采购价、货源备注不进入 Ozon 请求。
部分上架后只锁定**当前商品的型号 `common.model`**：任一 SKU 首次导入成功，后续草稿保存不得改动型号；前端禁用并解释原因，服务端在保存事务内核对已导入 SKU 后拒绝绕过页面的修改。型号对应 Ozon 属性 `9048`，后续新 SKU 沿用锁定值。品牌、描述及其他动态属性仍可修改并保存在 Atlas 草稿中；这些编辑不会自动更新已导入的 Ozon 卡片。若其他共同属性变化可能影响新 SKU 与旧卡片合组，发布预检给出差异提示，但不以“共同属性不可改”为由阻断草稿保存。
## 4. 页面流程与验证语义
1. 点击任一按钮时先检测编辑页脏数据。若有未保存修改，走现有带版本检查的保存草稿流程；保存失败或资料版本冲突时停止上架，并定位字段。之后以**服务端已保存快照**作为唯一发布输入。
2. 「上架至 OZON」只选当前平台下未成功导入的活动 SKU；已导入 SKU 不传给预检或发布接口，在确认摘要中展示其名称 / 货号及“此前已导入，本次未重复提交”的原因。正在提交的 SKU 另提示“提交处理中”，本轮不重复排队。若没有可提交 SKU，不创建 job。「部分上架」先展示 SKU 名称、货号、状态及就绪问题供勾选；已导入 / 正在提交的 SKU 不可选择，服务端遇到过时选择仍按现有 `SKU_ALREADY_IMPORTED` / `SKU_IMPORT_IN_PROGRESS` 拒绝。
3. 调用现有 `publish-preflights`，只针对本次提交集合检查。`refreshing` 显示目录刷新中并使用同一 SKU 集合重试；`blocked` 显示 SPU 与每个选中 SKU 的字段问题，禁止创建 job；`ready` 才展示最终确认摘要（店铺、类目、SKU 数、货号、价格、无库存说明）。
4. 用户确认后使用新的幂等键创建 `publish-jobs`。服务端在同一事务重新校验版本、店铺、SKU 状态、目录与字段并固定请求快照；前端先前的 `ready` 不作为授权凭证。
5. 返回 202 只表示任务已排队。页面轮询 job，展示逐 SKU `排队 / 提交 / 等待 Ozon / 已导入 / 失败`，保留 Ozon 的脱敏错误字段，允许用户修改失败 SKU 后重新发起新任务；已导入的绝不由此入口再次提交。
6. 任一入口都不静默剔除被选中的无效 SKU。一次 Ozon 调用可能出现逐 SKU 成功和失败，UI 按 item 结果汇总，不能把整批简单标成成功或失败。
已导入 SKU 的提示建议为：**“以下 SKU 已在当前店铺导入，本次未重复提交：{SKU 列表}。需要修改时，请到「在线商品」查看，并在 Ozon 后台处理。”** 列表过长时显示数量、前几项和展开入口。目前 `docs/api/online-listings.md` 定义的在线商品功能只有查看和同步，不能把按钮写成可直接跳转到 Atlas 在线商品编辑。只删除 Atlas 的采集箱或本地上架记录，不会删除 Ozon 商品，也不能据此开放再次导入；后续若实现平台删除与重上架，应单独设计安全的状态转换。
目前 `GET validation` 的总 `ready` 是“全部未导入 SKU 就绪”的汇总；部分上架应以所选 SKU 的 `publish-preflights.validation` 为准，不复用无选择范围的页面总标记。即使现行 `publish-preflights` 允许最多 100 个，本功能也应在页面、预检及创建 job 的服务端边界统一实施 **1–50 个 SKU** 的上限；超过 50 个时提示“本次最多上架 50 个 SKU，请使用「部分上架」分批提交”，不截取、不自动拆批。
现行 `docs/api/product-editor-and-publishing.md` 第 3 节还明确留下“类目树过期时如何保护真正发布”的待决项。创建 job 前需确定是否强制刷新整棵类目树；无论采用哪种策略，必须再核对所选类目仍在目标平台有效，不能只依赖编辑页先前看到的类目状态。
## 5. 服务端任务、媒体与失败恢复
- `POST /api/product-platform-profiles/{profile_id}/publish-jobs` 和 `GET /api/product-publish-jobs/{job_id}` 沿用现有预留路径；请求、响应和错误码先更新 `docs/api/` 与 `@atlas/contracts` 后实现。创建接口必须使用 `Idempotency-Key`，只接受当前工作空间、平台、profile 和店铺下的 SKU。
- 新迁移将 `product_publish_jobs`、`product_publish_job_items` 从架构草案落到真实数据库，补齐 `workspace_id`、复合外键、RLS、唯一约束、索引和可恢复的状态字段。与 listing 状态变更、Outbox 事件在同一事务提交；BullMQ 只传 job ID，不带密钥、商品全文或图片地址。
- Worker 读取加密保存的当前目标店铺 Ozon 凭据，按固定快照组装单批最多 50 个 item 的请求；在提交前批量查询远端 `offer_id`，避免 `/v3/product/import` 将外部已有同号商品当作更新。收到 `task_id` 后持久化，再轮询 `/v1/product/import/info`；`imported` 记录 `product_id`，`failed` 保存脱敏错误，`skipped` 先对账。商品审核与库存从 `/v3/product/info/list` 及在线商品同步单独读取。
- 网络超时或 Worker 崩溃时，先根据已存 `task_id` 或 `offer_id` 向 Ozon 对账；不确定请求是否已到达时不能直接重发导入请求。429 遵守官方重试头；5xx 有界退避；确定性 4xx 转成逐 SKU / 整批失败并保留可修复原因。重复 Outbox 消息与同幂等键请求不得重复上报。
- 已保存的 SKU 图片不是外部图片链接：采集图会先下载并转存 Atlas 对象存储，网络导入、用户上传和图片处理结果也存为正式素材；编辑草稿只保存 `asset_id` 和顺序。API 当前签发的 `preview_url` 是指向 Atlas 对象存储的**10 分钟预览凭证**，不随草稿持久化。不能直接把它当发布图片 URL，因为 Ozon 可能在链接失效后抓取，且本地默认对象存储 endpoint 为 `http://localhost:9000`，外网无法访问。
- 发布前需从这些 Atlas 正式素材提供**公网 HTTPS、可在 Ozon 异步抓取期间持续访问**的 JPG/PNG 图像交付链路；推荐专用不泄露桶 key 的随机访问 URL，绑定素材版本，可撤销并在任务完成后留合理抓取宽限期。发布快照存 asset ID / 版本，不持久化临时预览 URL 或密钥；WebP 转换在 Worker 中完成并验证实际公网可抓取性。生产对象存储端点及其公网可访问性尚需部署配置确认，不能从本地默认值推断生产环境一定不可访问。
- SKU 的历史首次导入 `offer_id` 和 `product_id` 锁定；已导入 SKU 的 Atlas 草稿编辑仍不隐式更新 Ozon。在线商品镜像保留其独立同步事实。
### 七牛 Kodo 图片交付调研结论
项目既有架构已选定本地 MinIO、共享测试与生产七牛 Kodo。七牛官方[私有资源下载](https://developer.qiniu.com/kodo/1656/download-private)文档定义私有资源的 `e`（秒级 Unix 过期时间）和 `token` 下载凭证，过期返回 401；[Node.js SDK](https://developer.qiniu.com/kodo/sdk/nodejs)提供 `privateDownloadUrl(domain, key, deadline)`；[自定义源站域名](https://developer.qiniu.com/kodo/8556/set-the-custom-source-domain-name)支持绑定 HTTPS 证书。因此**七牛支持给正式素材签发指定有效期的 HTTPS 私有下载地址**。这确认能力存在，尚不等于现有生产域名、证书、跨境抓取及 Ozon 异步抓图均已验收。
发布适配器应从 `media_asset` 的 bucket / object key 在提交前生成**独立于 10 分钟页面预览**的七牛下载 URL；对象存储 S3 API endpoint 继续用于上传与内部读取，给 Ozon 的 URL 使用已绑定的公网 HTTPS 下载域名。七牛的[S3 兼容服务域名](https://developer.qiniu.com/kodo/4088/s3-access-domainname)也支持 HTTPS，但其文档要求 AWS Signature，不能把该服务域名当成匿名图片地址。URL 有效期设为可配置、覆盖提交排队、Ozon 抓取和重试的窗口；具体时长及过期后 Ozon 是否再次抓图，必须在测试店铺做真实导入与延迟抓图验证。若平台需要长期稳定可抓取 URL，再评审专用发布副本 / 域名方案，不能凭文档推定签名短链永久足够。
当前若干素材入库路径仍将 `storage_provider` 写死为 `local_minio`，与已选定的生产七牛架构不一致。实施七牛联调前，应让入库记录按环境填写实际 provider，并验证从已有 `media_asset` 到正确下载域名的映射；不得仅把对象存储 endpoint 换成七牛地址就宣称发布图片可用。
实施时已更新 API 第 7 节：快照固化素材 ID / checksum / 存储身份，Worker 提交时签发独立 URL；每个 job 对应一个最多 50 SKU 的 Ozon task，混合成功失败汇总为 `partially_succeeded`。
## 6. 实施顺序与验收
| 阶段 | 修改范围 | 交付与验收 |
|---|---|---|
| A. 契约与数据 | `docs/api/`、`packages/contracts/`、`packages/database/migrations/` | 将 VAT 标为待目标店铺验证的可选适配字段，首期不因文档分歧强加必填税率配置；修订上架契约及旧 Ozon 整理稿；草稿约束改为货号 50、标题 500、图片 30，并处理历史超长草稿；建 job/item 表、索引/RLS；迁移可在空库与现有库运行，跨工作空间和同商品归属测试通过。 |
| B. 服务端快照与预检 | `apps/api/src/product-editor/` | 同一 SKU 集合重算目录和字段；草稿保存与发布预检均对超过 50 字符的货号给出定位提示，并校验价格、图片、型号锁定、已上架状态和每批 50 个上限；VAT 按已验证店铺策略省略或传已确认值；冻结逐 SKU 适配快照和 Outbox；并发、版本冲突、重复键、远端同货号用集成测试覆盖。 |
| C. Ozon Worker | `apps/worker/src/`、媒体交付模块 | 组装可验证的真实请求体，单批 ≤50 提交 / 轮询 / 对账 / 超时恢复；修正素材 provider 写入与下载域名映射，使用七牛公网 HTTPS 下载域名和可配置签名有效期；用固定夹具比对导入字段，模拟混合成功失败、`skipped`、429、进程重启和重复投递；在测试店铺验证跨境抓图和延迟抓图。 |
| D. 编辑页 | `apps/web/src/pages/products/`、`apps/web/src/services/` | 两个按钮、部分上架选择弹窗、保存→预检→确认→任务进度与逐 SKU 错误；全部上架跳过并列出已导入 SKU，待提交项有错则无 job；超过 50 个提示分批；首个 SKU 成功后型号不可改，其他草稿属性仍可编辑。 |
| E. 联调验收 | API / Worker / Web / Ozon 测试店铺 | 使用同类中国主体跨境 rFBS 店铺验证省略 `vat` 的真实导入、任务结果及 `/v3/product/info/list` 返回值，并与卖家店铺税务设置核对；未通过前不开放生产发布；再覆盖单 SKU、全部 SKU、部分 SKU、同 SPU 后续补上架、类目字典过期、图片抓取、Ozon 拒绝、超时重试、店铺货号冲突；typecheck/build 和受影响测试全部通过。 |
## 7. 评审时需确认的产品决策
1. **全部上架与已导入 SKU（已确认）**：只提交 `not_listed` / `failed`；已导入 SKU 保留并在摘要列出跳过原因，正在提交的 SKU 也不得重复排队。
2. **草稿长度（已确认）**：货号 50 字符、Ozon 发布标题 500 字符、每 SKU 图片 30 张，与 Ozon 当前导入限制对齐；旧超长值需人工修改。
3. **VAT（产品决策已确认，目标店铺联调待验证）**：中国主体、跨境 rFBS 的首期在导入 item 中省略 `vat`，不自动填 `"0"`；需以同类测试店铺真实导入和商品信息返回值验收省略后的行为，再开放生产发布。如果 Ozon 校验要求传值，或返回结果与卖家店铺税务设置不符，再由卖家向 Ozon 确认适用值并补店铺级配置；此时不得用默认 `"0"` 绕过。毛子 ERP 表单省略 `vat` 仅是参考，不能证明其发往 Ozon 的内容。
4. **多 SKU 条码与履约（已确认）**：首期仅 `rFBS`，可不传条码，不把 SPU 通用条码复制到多个 SKU；不在这次提交库存或仓库。
5. **每批数量（已确认）**：最多 50 个待提交 SKU；超出即提示使用部分上架分批操作，不自动拆批。
6. **部分上架后的型号（已确认）**：任一 SKU 成功导入即锁定 `common.model`；其他草稿属性可修改，但不会隐式更新 Ozon 已导入商品。
7. **图片交付（方案已确认，联调待验收）**：使用七牛私有正式素材的独立签名下载 URL，过期时间可配置，公网 HTTPS 域名与页面预览地址分离；生产域名 / 证书、Ozon 可抓取性、签名有效期以及 WebP 转码结果要在测试店铺验证。
2026-09-30：维护者确认 VAT 决策并授权按本方案开始开发；生产发布仍须完成 VAT 与七牛图片真实联调验收。
## 8. 本轮实施与验证
- 已实现两个入口、指定 SKU 预检、确认摘要、原子 job/item/Outbox 创建、请求幂等、冻结快照、远端货号检查、异步导入轮询及不确定提交对账。任何待提交项校验失败都不会创建批次；任一素材准备失败则本批剩余项全部失败、不发导入请求。
- 实际请求显式列出允许字段，省略 `vat`、条码、库存、仓库与顶层描述；金额保留十进制字符串。成功后锁定型号与历史货号，进行中禁止换店；完成后仍允许换店，已导入 SKU 保留原店铺事实。
- 图片校验 checksum、复制独立发布对象、WebP 转 JPEG；七牛私有 URL 默认 7 天，`OZON_IMAGE_URL_TTL_SECONDS` 可配置（至少 1 小时）。原有 MinIO 素材需迁移到七牛后再交付，不能仅改 provider 标签。
- 迁移 `055` 已在空白隔离库和本地开发库验证应用。API/编辑器/素材 26 项与 Worker 14 项测试通过，contracts/API/Worker/Web 类型检查与构建通过。浏览器使用隔离数据库验证全部选择、部分禁选、缺字段阻断、确认摘要、创建与刷新恢复；未调用真实 Ozon 导入。
- 生产 `OZON_PUBLISH_ENABLED=auto` 默认关闭。仍需配置七牛 S3 存储、HTTPS 下载域名与签名凭据，并在同类测试店铺验收 VAT 省略行为及延迟抓图，再显式启用生产上架。配置见根目录 `.env.example`。
docs/product/product-ai-editor.md
+2 -2
View File
@@ -9,7 +9,7 @@
```text
页头：返回 · 商品标题 · 当前平台 · 目标门店 · 当前平台上架状态 · 来源
├─ 主要信息
│ ├─ 类目、中文商品名、俄文发布标题、型号、品牌
│ ├─ 类目、中文商品名、俄文标题、型号、品牌
│ └─ 默认包装重量与默认包装尺寸
├─ 产品属性
│ ├─ 主题标签、简介、采买地址与货源备注
@@ -25,7 +25,7 @@
页面以编辑草稿工作，不采用字段失焦即写库。保存草稿需原子提交父商品、SKU、属性和媒体顺序；存在未保存修改时关闭页面须二次确认。SKU 定价确认是例外：它会即时持久化该 SKU 的价格与定价快照。
主要信息中的“中文商品名”用于 Atlas 内部识别；“俄文发布标题”是 SPU 共用发布标题，页面保存时必须填写。AI 填报仍可从俄文标题为空的采集草稿启动；发布前服务端会再次检查该字段。
主要信息中的“中文商品名”用于 Atlas 内部识别；“俄文标题”默认在 SPU 通用，也可切换为按 SKU 设置。草稿保存允许标题留空；首次上架前按当前标题模式校验所需标题。
采集进入采集箱时，商品**型号**和各 SKU 的目标平台**货号（Ozon `offer_id`）**默认都为空。进入编辑页后，用户可手动填写或点击“AI 填报”生成并直接填入表单；生成货号不直接照搬来源 SKU。型号属于商品通用资料，货号属于当前平台下的每个 SKU。两者允许随草稿保存而暂时为空，但首次上架校验必须全部通过：商品型号非空，且每个待上架 SKU 的货号非空并在目标店铺内唯一。详见[AI 填报方案](./ai-autofill-plan.md)。
docs/project/HANDOFF.md
+17 -8
View File
@@ -1,12 +1,12 @@
# Atlas Seller Kit 交接说明
> 更新：2026-09-29。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md) 和仓库 `AGENTS.md`。下方按日期记录的旧方案仅供追溯；当前状态以本节、2026-09-29 类目佣金记录及最新的 1.47 节为准。
> 更新：2026-09-30。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md) 和仓库 `AGENTS.md`。下方按日期记录的旧方案仅供追溯；当前状态以本节、2026-09-29 类目佣金记录及最新的 1.47 节为准。
## 1. 项目定位
这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享契约、数据库包和本地基础设施。认证、工作空间隔离、门店/素材、采集箱、商品编辑草稿、平台级商品参考目录、发布预检和商品 AI 填报已有实现；SKU 定价试算与确认、在线商品同步已有实现，真正的 Ozon 首次发布仍待接入。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件；复用纯规则前须适配多租户和云端边界。
pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享契约、数据库包和本地基础设施。认证、工作空间隔离、门店/素材、采集箱、商品编辑草稿、平台级商品参考目录、发布预检和商品 AI 填报已有实现；SKU 定价试算与确认、在线商品同步已有实现，Ozon 首次发布已实现，真实店铺 VAT 和七牛图片交付仍待验收。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件；复用纯规则前须适配多租户和云端边界。
当前运行时基线：Node 24.20.0、pnpm 11.25.0、PostgreSQL 18.6、Redis 7.4.11、MinIO `RELEASE.2025-09-07T16-13-09Z`；Web 默认端口为 `8100`，API 默认端口为 `8200`，扩展 dev server 默认端口为 `8110`（仅本地开发用），Worker 无 HTTP 端口。完整目录、依赖边界与版本表见 [`architecture/project-structure.md`](../architecture/project-structure.md) 和 [`architecture/technology-and-deployment.md`](../architecture/technology-and-deployment.md)。
@@ -14,12 +14,21 @@ pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、
已完成“采集 → 采集箱 → 商品编辑草稿”的主要数据闭环、平台级类目/属性/字典目录与发布预检。编辑页已接入异步「AI 填报」：基于来源资料与 Atlas 类目树生成类目建议、型号/SKU 货号、证据充分的包装建议及 SPU 中俄文案；单 SKU 文案由用户单独生成并确认应用。AI 结果只回填未保存表单，保存草稿仍是持久化边界。Ozon 动态类目属性可按已选类目加载并手工填写，**当前不由 AI 自动填报**。SKU 图片选择现支持采集候选图、工作空间上传图和网络导入图；在弹窗确认后回填草稿，页面保存后持久化。
SKU 定价已打通试算、表单应用与原子保存确认，在线商品同步已有 API/Worker。可直接发布的闭环仍缺真正的 Ozon 发布 job/import 及结果轮询；正式定价还需完成 CEL 费率及类目佣金映射审核。AI 类目推荐和文案已能运行，但不能等同于跨来源样本验收；尤其应继续用 1688/淘宝/天猫样本核验 Atlas 类目候选质量，以及俄文文案、包装证据和 SKU 继承行为。AI 套图生图仍是占位入口；图片「编辑」菜单中的一键 3:4、添加水印和单张 AI 编辑已接入异步素材任务。
SKU 定价已打通试算、表单应用与原子保存确认，在线商品同步已有 API/Worker。首次发布 job/import 与结果轮询已接入；生产启用仍需完成 VAT 与七牛图片交付验收；正式定价还需完成 CEL 费率及类目佣金映射审核。AI 类目推荐和文案已能运行，但不能等同于跨来源样本验收；尤其应继续用 1688/淘宝/天猫样本核验 Atlas 类目候选质量，以及俄文文案、包装证据和 SKU 继承行为。AI 套图生图仍是占位入口；图片「编辑」菜单中的一键 3:4、添加水印和单张 AI 编辑已接入异步素材任务。
当前优先事项：用真实来源样本回归 AI 类目推荐、文案与图片选择，补做真实图片上传/网络导入联调；审核正式物流费率与佣金映射，并用实际结算账单核对 Ozon 平台服务费、收款费和其他扣费；让首次发布 job 复用既有发布预检，再实现 Ozon import 与结果轮询。平台参考目录目前由平台级参考源和同步任务维护，不能把 9 月 10 日的门店级缓存描述当作现行架构。
当前优先事项：用真实来源样本回归 AI 类目推荐、文案与图片选择，补做真实图片上传/网络导入联调；审核正式物流费率与佣金映射，并用实际结算账单核对 Ozon 平台服务费、收款费和其他扣费；完成首次发布在中国主体跨境 rFBS 测试店铺的 VAT 省略与七牛延迟抓图验收。平台参考目录目前由平台级参考源和同步任务维护，不能把 9 月 10 日的门店级缓存描述当作现行架构。
接手前请先阅读 `git status --short`，确认当前工作区状态；本轮图片选择的 Web、API、contracts、迁移、测试和文档随本报告一起提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。开发验证需要时可按 `AGENTS.md` 先确认进程与端口，再启动或重启 API/Worker；下方旧章节中的“不可重启”说法已失效。
### 2026-09-30：商品编辑页首次上架
- Web、API、Worker、contracts 与 database 同步实现，接口以 [商品编辑与首次上架 §7](../api/product-editor-and-publishing.md) 为准；研究、产品决策及验收见 [实施记录](../product/ozon-first-publish-review-plan.md)。扩展未改动。
- 两个入口为「上架至 OZON」「部分上架」，只提交未导入或失败 SKU，显示已导入/进行中的跳过原因；每批最多 50，先保存草稿、预检和确认，再原子写入不可变快照及 Outbox。成功锁定型号和历史货号，其他资料仍能保存。任务状态可刷新恢复。
- Worker 提交前检查远端货号，导入后轮询；受理结果不确定时仅对账，禁止盲目重发。七牛图片校验 checksum、复制发布对象、WebP 转 JPEG，再签发独立私有 HTTPS 下载地址，默认 7 天；不持久化签名或 URL。
- VAT 按维护者确认首期省略，不默认 `0`；rFBS 首期不提交条码、库存和仓库。生产 `OZON_PUBLISH_ENABLED=auto` 默认关闭，真实店铺与图片验收后显式启用。MinIO 素材不能直接供 Ozon 抓取，需要迁移到七牛；环境项见 `.env.example`。
- `055` 全量空库迁移和本地开发库应用通过。26 项 API/编辑器/素材与 14 项 Worker 测试通过；contracts/API/Worker/Web 类型检查与构建通过，Web 仍有既有 bundle 提示。隔离库浏览器验证了禁选、全部/部分预检、缺字段阻断、提交及刷新恢复，未发送真实 Ozon 导入。
- 维护者原有 API8200、Web8100、Worker 保持运行，通过监听自动加载改动；验证用 API8201、Web8101 已关闭，隔离测试库已清理。
### 2026-09-29：类目佣金 JSON 导入与定价接入
- 已先编写[实施方案](../product/category-commission-import-plan.md)，并完成[API 契约](../api/category-commissions.md)、迁移 `052`、导入解析器、原子启用、管理页面及试算展示。影响 Web、API、contracts、database；未涉及 Worker 和扩展。
@@ -468,7 +477,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
- 全局填报读取 Atlas 平台级活动类目树，按层向模型提供有限候选；对大分支分段初选、再决选，只接受给定选项。明确结果可回填类目，有多个命中则在「确认 AI 推荐类目」弹窗中由用户选择。已有类目不被覆盖；未确认类目时不能生成依赖它的型号和货号。型号是 SPU 共用稳定码，未导入 SKU 的货号分别生成并检查长度、连接符及冲突。
- 全局文案只生成 SPU 的俄文标题、主题标签、产品描述及逐项中文对照；描述要求概述与「Характеристики:」分段、项目符号。SKU 默认继承 SPU 三项文案；用户可打开当前 SKU 的 AI 弹窗，预览后明确点击应用，才写入该 SKU 的未保存表单。SPU/SKU 都有中俄对照查看入口，俄文被手工修改后旧中文对照标为待更新。
- 包装重量和尺寸仅在来源有可逐字核对的证据时建议；缺证据则留空。原计划的「AI 填写 Ozon 类目属性」已撤回：当前只在类目确定后按 schema 动态加载商品/SKU 属性，用户自行填写。`030_product_ai_attribute_fill.sql` 与历史 `attribute_fill` 类型保留兼容，不代表当前仍会创建或执行该任务。
- 编辑页已把「内部商品名」文案改为「中文商品名」，「俄文发布标题」在表单与发布就绪校验中必填；SPU 标题有加号入口开启 SKU 标题覆盖。SKU 的 Ozon 变体字段已并入「SKU 信息」，不另设「Ozon 变体属性」标题。底部 `editor-footer` 固定在视口底部；AI 类目候选弹窗已调整为说明、单选候选和明确确认操作。类目输入框清除时的空值处理已修正。
- 编辑页已把「内部商品名」文案改为「中文商品名」；「俄文标题」默认在 SPU，支持切换为按 SKU 设置并持久化模式。草稿保存允许标题留空，首次上架预检按通用或逐 SKU 模式检查。SKU 的 Ozon 变体字段已并入「SKU 信息」，不另设「Ozon 变体属性」标题。底部 `editor-footer` 固定在视口底部；AI 类目候选弹窗已调整为说明、单选候选和明确确认操作。类目输入框清除时的空值处理已修正。
- 最新俄文文案规则同时作用于 SPU 与 SKU Prompt：`title.ru`、`tags[].ru`、`description.ru` 不得出现汉字；来源中文事实应翻译为自然俄文，只有有依据的拉丁品牌/型号及阿拉伯数字可保留。Worker 结果校验会丢弃仍含汉字的对应字段，中文对照与包装原文证据不受此限制。旧已保存文案不会自动改写，需重新生成或手工修订。
**验证状态与下一步**
@@ -567,7 +576,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
| 采集 SKU | 只有来源给出稳定 SKU/组合证据时创建多个 SKU；不能把规格轴做笛卡尔积。没有专属 SKU 图时，真实 SKU 继承父商品默认图而不复制资产。 |
| 媒体 | 采集主图/详情图是商品候选池；来源明确给出 SKU、或可靠的规格轴值（如颜色）与图片关系时才自动绑定。其余素材由编辑页人工选择。 |
| 发布与在线商品 | 商品采集、编辑、定价、AI 媒体和首次导入至 Ozon 后台是核心闭环。正式发布使用官方 Seller API，按一 SKU 一 import item/offer 执行并轮询结果；首期不传库存或仓库，用户在 Ozon 后台设置库存。已导入 SKU 不可再次上架，未上架 SKU 仍可首次上架；SPU 在当前平台汇总为未上架/已部分上架/已上架。在线商品由异步 Ozon API 同步，按 Ozon 商品 SKU 展示，亦包含非 Atlas 发布商品。 |
| 平台商品参考目录 | `platform_id` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面、手动排队、商品编辑器读取和发布预检已实现；真正的 Ozon 发布 job 待开发。 |
| 平台商品参考目录 | `platform_id` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面、手动排队、商品编辑器读取和发布预检已实现；真正的 Ozon 发布 job 已实现，真实店铺联调待验收。 |
## 3. Ozon 已核对结论
@@ -602,7 +611,7 @@ User → Workspace → Membership / Role
- 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。
- **响应信封是强制契约：** 成功单资源或同步动作返回 `{ "data": T }`，列表返回 `{ "data": T[], "meta": PaginationMeta }`，失败返回 `{ "error": ApiError }`，`204 No Content` 不返回响应体。项目不采用完整 JSON:API；任何调用方不得自行增加嵌套 `data` 或以 `data: null` 表示错误。完整规则见 [`api/conventions.md`](../api/conventions.md)。
- 关键异步动作必须在同一事务写入业务记录、`operations`（如需用户可见进度）和 `outbox_events`；Dispatcher 至少一次投递 BullMQ，Worker 必须幂等。
- 早期 DDL 已通过本地隔离 PostgreSQL 验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证、采集清理、来源素材转存及商品 AI Worker 已有实现。新近 `029`/`030` 迁移在目标环境中的应用状态需单独核对；商品发布和在线商品同步 Worker 仍待实现。
- 早期 DDL 已通过本地隔离 PostgreSQL 验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证、采集清理、来源素材转存及商品 AI Worker 已有实现。新近 `029`/`030` 迁移在目标环境中的应用状态需单独核对；商品发布和在线商品同步 Worker 已实现，真实平台联调状态见最新记录。
仍需在对应模块开始编码前完成的 P1/P2 决策和数据模型补丁，集中记录在 [`reviews/implementation-readiness-open-items.md`](../reviews/implementation-readiness-open-items.md)。
@@ -616,7 +625,7 @@ User → Workspace → Membership / Role
1. 核对 AI 任务迁移、运行进程版本和四类来源的真实样本；回归类目选择、中俄文案（俄文字段不含汉字）、包装证据、SKU 文案继承及候选媒体按需物化，并联调 SKU 图片上传、网络导入与保存。
2. 完成定价确认、平台目录大字典续传与管理员浏览器回归；旧门店目录继续保留，暂不清理。
3. 将真正的 `publish-jobs` 创建事务接入已完成的发布预检，固化发布快照后实现 Ozon `/v3/product/import` 与结果轮询，再推进在线商品同步；不得重新实现另一套目录判断。
3. 首次发布 job、快照、Ozon 导入/轮询和在线同步已实现；下一步完成真实中国主体跨境 rFBS 店铺的 VAT 省略和七牛图片交付验收。
### 历史计划（仅供追溯）