feat(ai-edit): 开发 AI 填报功能
This commit is contained in:
R524809
@@ -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 } } }
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 商品 AI 编辑页
|
||||
|
||||
> 状态：商品编辑主流程和 Ozon 动态属性 P0 已实施，平台类目/属性/字典读取及首次发布预检已迁移完成；定价确认、AI 任务和真正调用 Ozon 的发布 job 仍有未实施部分。准确接口状态以 [`../api/product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 和 [`../project/HANDOFF.md`](../project/HANDOFF.md) 为准。
|
||||
> 状态（2026-09-23）：商品编辑主流程、Ozon 动态属性 P0、平台级目录读取、首次发布预检及商品 AI 填报/单 SKU 文案任务已有实现；Ozon 动态属性由用户填写，当前不由 AI 自动填报。定价确认、AI 生图、真正调用 Ozon 的发布 job 与在线商品同步尚未完成。实际验收边界以 [`../api/product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 和 [`../project/HANDOFF.md`](../project/HANDOFF.md) 为准。
|
||||
|
||||
## 目标
|
||||
|
||||
@@ -23,6 +23,7 @@
|
||||
## 分册
|
||||
|
||||
- [页面与交互](./product-ai-editor.md)
|
||||
- [AI 一键填报开发与设计方案](./ai-autofill-plan.md)
|
||||
- [Ozon 动态属性与 SKU 填报改造方案](./ozon-dynamic-attributes-and-sku-form-plan.md)
|
||||
- [数据库领域模型](./data-model.md)
|
||||
- [服务端 API 契约](./api.md)
|
||||
|
||||
@@ -0,0 +1,140 @@
|
||||
# 商品 AI 填报：设计与开发方案
|
||||
|
||||
> 状态：2026-09-23 已实现。目标平台首期为 Ozon；采集来源覆盖 Ozon、1688、淘宝、天猫。全局 AI 填报和 SKU 文案通过异步任务回填未保存表单；动态类目属性不在当前范围。
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
用户采集商品、进入编辑页并点击底部唯一的「AI 填报」按钮后，系统依据已经保存的采集资料、当前草稿和 Atlas 平台参考目录，生成类目、型号、每个未导入 SKU 的货号、证据充分的包装规格，以及 **SPU 的** Ozon 俄文标题、主题标签和产品描述。任务完成后，页面**直接将合格结果写入当前表单**，标记为未保存修改；用户可以继续改动，并通过现有「保存」操作统一持久化。生成任务本身不修改商品草稿、店铺或 Ozon 商品。SKU 三项文案默认继承 SPU；用户展开 SKU 字段后可针对当前 SKU 单独触发 AI 生成。
|
||||
|
||||
AI 不生成售价、采购价、品牌、条形码、图片、富内容、动态类目属性或已导入 SKU 的货号。类目改变后仍由现有机制加载属性 schema，并由用户按既有控件填写。输入资料不足时允许部分填报，不能为了填满表单编造重量、尺寸或商品事实。
|
||||
|
||||
该能力的内部入口是「已规范化商品资料 + 目标平台 + 可售 SKU + 草稿版本」，而不是 React 页面。未来从商品详情链接直接采集后，先进入现有采集规范化链路，再调用同一 AI 填报服务。
|
||||
|
||||
## 2. 现状与可行性
|
||||
|
||||
- Atlas 已有 `source_material`、`source_material_state.latest`、`ai_input`、平台级类目树、商品/SKU 草稿、版本号及 `editor-draft` 原子保存接口。底部现有类目和文案两个占位按钮，可合并为一个入口。
|
||||
- Atlas 现有 AI API 是尚未实施的任务契约：先保存草稿，再创建异步任务，结果由用户应用。此次保持「先保存」和「任务不写草稿」，但把结果应用动作改为任务完成后直接写入浏览器表单；页面现有保存按钮仍是数据库写入边界。
|
||||
- 旧版 `ozon-seller-kit` 的 `server/services/prompts/copy_ru.py` 已定义中俄成对的标题、描述和标签及事实边界；`server/services/deepseek.py` 实现 JSON 请求、解析和一次纠错重试。可复用规则和测试样本，不直接复制旧版 FastAPI、无工作空间隔离的调用路径或试算页「生成后立即保存简介」行为。
|
||||
- DeepSeek 官方 JSON 输出文档支持 `response_format: {"type":"json_object"}`，同时提示空内容和输出截断的可能性。因此 JSON 模式只保证可解析性的目标，**不替代 Atlas 的字段 schema、事实引用、类目 ID、长度和唯一性校验**。具体模型名和参数应作为服务端配置，经上线时再次确认。
|
||||
- 当前迁移尚无 `product_ai_tasks` 实表；`docs/architecture/sql/002_product-domain.sql` 仅有设计草案。落地任务状态、结果和中文对照需要新迁移。
|
||||
|
||||
## 3. 一次点击的页面流程
|
||||
|
||||
1. 用户点击「AI 填报」。若表单有未保存修改，页面先调用现有保存流程；保存失败时不创建任务。当前 `source_snapshot_revision`、商品/profile revision、SKU ID、目标店铺和平台由服务端固化为任务输入快照。
|
||||
2. 页面将底部按钮改为「填报中…」，显示步骤：分析采集资料 → 推荐类目 → 生成文案与编号 → 校验结果。用户可继续浏览页面。重复点击沿用同一输入版本的进行中任务，避免重复计费。任务以字段组为独立产出单元：类目、编号、包装和文案可以分别成功或失败；只有完全没有合格结果才记为整体失败。
|
||||
3. Worker 完成后，服务端返回已校验结果、警告及中俄文案。页面核对任务快照与当前编辑版本；若复采或草稿有新版本，提示结果已过期，不自动回填。
|
||||
4. 在同一版本下，页面直接写入符合规则的表单字段并显示「已填报 N 项，M 项待处理／证据不足」。任务部分成功时，合格字段照常回填，失败字段保留原值并按原因列出。类目写入表单后触发已有动态 schema 加载；旧类目属性草稿按现有切换规则处理。本期不让 AI 接续填写新 schema。
|
||||
5. 已导入 SKU 的货号不变；全局结果只填空字段，原本由用户填写的非空字段保留。异步等待期间若草稿版本变化，本次结果不回填。
|
||||
6. 回填只改变浏览器表单并触发页面 `dirty` 状态。关闭页面前继续使用现有未保存提示；保存后与其他草稿字段一同持久化。
|
||||
|
||||
不增加逐字段确认弹窗。字段建议、被跳过项目和原因可在一个简短的填报结果面板查看；用户最终通过编辑页原有的保存动作提交。生成失败或部分字段失败时，已校验合格的其他字段仍可应用。
|
||||
|
||||
## 4. 字段规则
|
||||
|
||||
### 4.1 类目
|
||||
|
||||
- Ozon 来源先使用现有「一级面包屑 + `Type_0` 商品类型」匹配；已经有用户选择的类目不因 AI 填报改变。确定性匹配唯一时沿用它，不再为该字段消耗模型调用。
|
||||
- 1688、淘宝、天猫来源无 Ozon 类目 ID。服务端向模型分层提供 Atlas **活动、可发布目录**：先给顶层选项，再按选定分支给子节点，直到叶子；每一步只允许返回给定 UUID，并记录候选路径和理由。不得让模型自造类目名或把来源平台类目 ID 当成 Ozon ID。
|
||||
- 最终叶子由服务端复核所属平台、活动状态、可发布 `description_category_id + type_id` 以及祖先链。证据明确时把 Atlas 叶子 UUID 填入未保存表单，`category_source=ai_suggestion`；歧义或证据不足时不填，并显示至多三个候选供用户通过现有类目控件选择。
|
||||
- 不用模型自报的置信度单独决定是否回填；自动回填阈值应基于四来源样本评测校准。已保存的用户类目优先级高于新建议。
|
||||
- 类目目录若缺失、未同步完整、已失效或目标叶子缺少有效 `description_category_id + type_id`，先复用现有目录同步机制；在有界等待后仍不可用时，类目结果标为 `catalog_unavailable`，不向 AI 提供不完整候选，也不自造类目 ID。已有已确认类目可继续作为其他字段的上下文；否则依赖类目码的型号与货号暂不生成。文案和有独立证据的包装建议照常处理。
|
||||
- 这里的类目目录与 Ozon **动态属性字典**不同。类目确认并保存后，页面只加载 schema，动态属性由用户通过既有下拉搜索和输入控件填写；当前 AI 填报不处理属性及字典值。
|
||||
|
||||
### 4.2 型号与 SKU 货号
|
||||
|
||||
- **同一 SPU 只有一个 `model`**，不随 SKU 的作品、角色、颜色变化。AI 先归纳所有 SKU 真实共有的商品类型与形态；只有全部 SKU 确实属于同一系列时，系列语义才允许进入型号。死亡笔记、海贼王、火影忍者等作品混在一个手办 SPU 时，公共型号使用中性的类别/形态码，如 `FIG-MIX-8K4F`，绝不取首个 SKU 的作品名当整组型号。若 SKU 连基本商品形态都不同，提示先拆分 SPU，不强行生成共同型号。
|
||||
- 格式由服务端固定：`model = 类目短码-共通形态或 MIX-商品稳定码`，例如 `FIG-MIX-8K4F`；只用大写英文字母、数字和 `-`，最多 **32 个 ASCII 字符、2 个连接符**。短码来自 Atlas 维护的跨平台商品形态码表，由目标类目映射而来，不直接使用 Ozon 专有 ID；AI 只建议共有语义，不能直接输出最终编号。模型不可用但类目明确时，可保守回退 `MIX`；无可用类目时不生成编号。类目名称或 SKU 排序变化后，不自动重编已经保存的型号。
|
||||
- 每个未导入 SKU 的 `offer_id = model-变体识别码`，识别码可由作品、角色和必要规格组成。例如 `FIG-MIX-8K4F-DN-L`、`FIG-MIX-8K4F-OP-LUFFY`、`FIG-MIX-8K4F-NAR-SASUKE`。整串最多 **48 个 ASCII 字符、4 个连接符**，通常为 3～4 个连接符；额外的颜色/尺寸须压入已有变体段，不能不断追加 `-`。只有来源明确提供作品/角色时才使用其缩写，不能凭图片猜测 IP；语义不可靠时改用基于稳定 SKU 身份的 `V` 码。变体识别码在本 SPU 内必须唯一，不依据显示顺序生成 `V01/V02`。
|
||||
- 服务端维护短码、缩写、稳定商品码及 SKU 身份的映射；AI 不负责计数或唯一性。生成后对本次所有 SKU、目标店铺已有草稿和在线镜像检查冲突；冲突时仅调整尚未保存的新码并保持上述长度/连接符上限，仍冲突则跳过该货号并报告。保存时仍由数据库唯一索引和现有服务端校验兜底。
|
||||
- 当前通用保存契约仅有较宽的 `model ≤ 300`、`offer_id ≤ 500` 字符上限。上述 32/48 及连接符规则是**AI 生成值的强校验**，不应悄悄拒绝已有或手填的较长编号；如要统一收紧所有编号，需要先盘点历史值并单独迁移、通知用户。
|
||||
- `model` 是跨平台商品字段，也会映射到 Ozon「型号名称」属性。本期按用户希望使用可识别编码；后续若需要单独的内部编码与对外型号，应新增独立字段，不能在生成逻辑里偷偷分叉。
|
||||
- 已导入 SKU 的货号是历史事实；AI 结果绝不填入或改动。手填非空型号/货号按页面覆盖规则保留。
|
||||
|
||||
### 4.3 包装重量与尺寸
|
||||
|
||||
- 只从明确的「包装/外箱/包裹」事实提出建议，区分商品本体的尺寸、净重和物流包装规格。模型为每个建议返回原文证据片段、来源字段、原单位和换算后的 `g/mm` 数值。
|
||||
- 服务端检查证据存在、单位可识别、值为正数且数量级合理。若只有商品尺寸或重量、只看图片推测、三维缺项或存在多种包装版本，相关字段保持空值或现有值，不生成“确切数值”。
|
||||
- 商品级包装建议填 SPU 默认值；仅当某 SKU 有专属包装证据时填该 SKU 覆盖值。有明确证据的结果字段状态为 `suggested`，允许直接回填；回填后的包装**确认状态**先标为 `ambiguous`，用户核对后改为 `confirmed`。证据本身有歧义的结果字段状态为 `ambiguous`，不自动回填。因此 AI 可减少录入，但不能绕过定价和发布所需的包装确认。
|
||||
|
||||
### 4.4 SPU 默认文案、SKU 按需文案与中文对照
|
||||
|
||||
- 三项指**发布标题、主题标签、产品描述**。底部「AI 填报」只生成 SPU 三项及逐项中文对照，不生成、不写入 SKU 三项覆盖值。SPU 文案只能陈述所有 SKU 都成立的共有事实；不同作品混在一组手办 SKU 时，不把其中一个作品写成 SPU 通用事实。
|
||||
- SPU 各字段旁的 `＋` 只开启对应 SKU 字段编辑入口，**不批量复制 SPU 文案、不隐藏 SPU 字段**。各 SKU 的标题、标签和描述逐字段默认继承 SPU；表单显示有效值和「继承 SPU」状态，只有用户手动输入或主动应用该 SKU 的生成结果才保存覆盖。
|
||||
- SKU 三项字段旁的 AI 图标打开同一个当前 SKU 生成弹窗。左侧展示中文来源描述、SKU 名称、规格和可证的作品／角色资料；点击「AI 生成」仅为该 SKU 生成俄文标题、标签、描述及中文配对，右侧预览，点击「应用到当前 SKU」才把合格结果写入该 SKU 的未保存表单。已有手工覆盖不得被静默替换。某项证据不足时可单独保持继承，其他合格项仍可应用。
|
||||
- 参考旧版提示词，每次文案生成可返回两组标题候选及逐项中文，默认采用第一组；标签逐项中俄配对，描述按段落对应。俄文是发布表单值，中文只是对照资料，不进入 Ozon 发布 payload。不得编造材料、认证、配件、安全性、产地、适用年龄、包装或功效；也不得把 A SKU 的角色、颜色或规格写到 B SKU。
|
||||
- SPU 和每个 SKU 的三个字段旁另有「中文对照」图标。统一弹窗左列展示当前有效俄文，右列展示对应中文，标题标明 SPU 或 SKU；继承项显示 SPU 对照与「继承 SPU」。中文对照按 `profile_id + scope(SPU/SKU) + variant_id + field` 保存配对版本；继承项只引用 SPU 对照，不复制记录。手工改俄文后若不再与中文配对，标记「中文对照待更新」，不得把 SPU 中文错配给 SKU 俄文覆盖。
|
||||
|
||||
## 5. 可复用服务与当前接口
|
||||
|
||||
全局入口使用 `POST /api/product-platform-profiles/{profile_id}/ai/autofills`；当前 SKU 的独立文案入口使用 `POST /api/product-platform-profiles/{profile_id}/variants/{variant_id}/ai/copy`。两者均要求 `Idempotency-Key` 和平台头，body 可带 `hint`；返回 `202 { ai_task_id, status }`。`GET /api/product-ai-tasks/{ai_task_id}` 返回任务状态、输入版本与已校验结果，不返回提示词、密钥或原始模型响应。Worker 从服务端 `.env` 读取 `DEEPSEEK_API_KEY` 与 `DEEPSEEK_MODEL_NAME`。
|
||||
|
||||
全局结果包含 `category` 或 `category_candidates`、`model`、`offers`、可选 `package_spec`、`spu_copy`、`warnings`。单 SKU 结果只包含 `variant_id`、`copy`、`warnings`。任务输入固化商品、profile、来源快照版本和 SKU ID；前端在回填前再次比对版本。
|
||||
|
||||
接口结构示意（实际契约见 `@atlas/contracts`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"kind": "autofill",
|
||||
"status": "partial",
|
||||
"input_revision": { "product": 12, "profile": 7, "source_snapshot": 4 },
|
||||
"result": {
|
||||
"category": { "category_id": "atlas-category-uuid", "path": "目录路径" },
|
||||
"model": "FIG-MIX-8K4F",
|
||||
"offers": [{ "variant_id": "variant-uuid", "offer_id": "FIG-MIX-8K4F-V123456" }],
|
||||
"spu_copy": {
|
||||
"title": { "ru": "…", "zh": "…" },
|
||||
"tags": [{ "ru": "…", "zh": "…" }],
|
||||
"description": { "ru": "…", "zh": "…" }
|
||||
},
|
||||
"warnings": ["未找到可核对的包装重量和尺寸"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
任务状态区分 `succeeded`、`partial`、`failed`；部分失败通过 `warnings` 表达。候选类目不自动回填，由用户点击候选确认。包装缺少可核对证据时不返回包装建议。
|
||||
|
||||
内部拆为四个与页面无关的组件：
|
||||
|
||||
1. `SourceFactAssembler`：把采集快照和已保存的用户整理稿转为带证据的、长度受限的规范化商品事实；未来 URL 入口复用此层。
|
||||
2. `CategoryResolver`：已有类目优先沿用；否则分层查询平台目录并向模型提供封闭候选，返回经数据库验证的叶子 UUID 或需用户确认的多个候选。
|
||||
3. `AutofillGenerator`：Worker 调用 DeepSeek 生成中俄文案与有证据的包装建议；稳定型号/货号由服务端规则生成。API Key 只在 Worker 环境读取，不进入浏览器、任务输入、outbox 或日志。
|
||||
4. `AutofillValidator`：校验中俄配对、包装证据与正数、类目 UUID、编号长度和货号冲突，丢弃不合格字段。
|
||||
|
||||
NestJS 负责鉴权、工作空间事务、快照和任务创建；任务与 outbox 在同一事务入库；Worker 调用模型和写回结果。调用超时、限流、空响应、截断和非法 JSON 使用有界重试，重复任务以任务 ID 幂等。失败只更新任务状态，不触碰草稿。记录模型、提示词版本、耗时和 token 用量以便成本分析；日志及对外错误只输出脱敏摘要。
|
||||
|
||||
迁移 `029_product_ai_autofill.sql` 建立任务和中俄对照表，并给 SKU listing 增加可空 `title`；`null` 表示继承 SPU 发布标题。SKU `tags=[]`、`description=null` 继续表示继承。中文对照随草稿事务保存、随编辑快照读取；表单俄文若与对照时的俄文不一致，页面显示「待更新」。
|
||||
|
||||
页面只回填空白的全局字段和 SPU 文案，不覆盖已有手填值；SKU 文案必须由当前 SKU 弹窗单独生成，并经用户点「应用到当前 SKU」才覆盖其标题、标签、描述。中文只进入对应作用域的对照记录。回填只改变未保存的表单状态，不独立写入草稿。
|
||||
|
||||
## 6. 版本、冲突与失败处理
|
||||
|
||||
| 情况 | 页面行为 |
|
||||
|---|---|
|
||||
| 任务期间用户改了部分字段 | 页面保存前先固化草稿；任务完成时若版本已变化，拒绝整次自动回填并提示重新生成。 |
|
||||
| 任务期间商品被复采、平台或 SKU 集合改变 | 结果标为过期，不自动回填；用户可重新点击生成。 |
|
||||
| AI 找不到可确定的目标类目 | 类目留空，展示候选；文案和有独立证据的包装仍可回填。若已有已确认类目，可继续生成型号与货号；否则编号留空。 |
|
||||
| 类目目录不完整或同步失败 | 无已确认类目时，型号与货号跳过；其他独立字段仍可回填。 |
|
||||
| Ozon 动态属性字典缺失 | 本期不由 AI 填报该属性，不影响其他字段；页面显示字典加载状态，保存草稿允许缺失，发布预检继续阻止无效字典值。 |
|
||||
| 包装数据没有明确证据 | 包装项留空，说明缺失，不将商品尺寸当包装尺寸。 |
|
||||
| 目标店铺货号冲突 | 服务端重算稳定后缀；仍冲突则仅跳过该 SKU 货号并提示。 |
|
||||
| DeepSeek 超时、限流、空响应或截断 | 按错误类别执行有界退避重试；仍失败则模型依赖组标为失败，确定性类目/编号组若已合格可形成 `partial`，否则任务为 `failed`；已填值不回滚，未填值保留原样。 |
|
||||
| 结构不合法或事实/字段规则不合格 | JSON 请求有限次重试；仍失败则拒绝模型依赖组。可解析时逐字段校验，中俄不成对或数值无证据的字段单独丢弃。 |
|
||||
| 当前 SKU 文案失败 | 弹窗显示错误；原 SKU 文案不变，不影响已生成的 SPU 文案或其他 SKU。 |
|
||||
| 用户修改俄文后查看中文对照 | 标记「对照待更新」，不把旧中文当作当前俄文的翻译。 |
|
||||
|
||||
## 7. 实施顺序与验收
|
||||
|
||||
1. **契约与迁移**：修订 `docs/api/`、`@atlas/contracts`；落地 AI 任务、SKU 发布标题和分作用域中文对照表、工作空间 RLS、outbox 事件与幂等键。测试跨工作空间不可读取任务/对照及 SKU 标题继承。
|
||||
2. **服务端核心**：事实组装、平台目录分层候选、DeepSeek JSON 输出校验、稳定型号/货号规则、包装证据校验。全局只生成 SPU 文案；当前 SKU 文案由独立任务按需生成。不使用真实密钥跑自动化测试。
|
||||
3. **编辑页**：合并底部按钮、任务轮询、表单直接回填和保存前版本保护；类目回填触发现有 schema 请求，AI 不碰动态属性。SKU 展开区补独立标题编辑，标签/描述改为逐字段继承 SPU，留空即继承。
|
||||
4. **中文对照**：SPU 和每个 SKU 的三个字段旁入口、统一双栏弹窗、继承来源标记、随草稿保存与重新加载、各作用域俄文编辑后的过期提示。
|
||||
5. **端到端验收**：维护者启动 API/Worker 并完成迁移后，用 Ozon、1688、淘宝、天猫样本回归；覆盖跨作品 SKU、单 SKU 按需生成、中文对照刷新后读取、已导入 SKU 货号保护、无包装证据、歧义类目、模型异常及复采并发。
|
||||
|
||||
完成标准：点击一次「AI 填报」后，页面出现合格的类目、型号、未导入 SKU 货号及 SPU 俄文文案；证据不足的包装项保持空白。用户可以再对指定 SKU 单独生成并确认文案；中文对照保存后仍可查看。动态 Ozon 类目属性由后续单独设计。
|
||||
|
||||
## 8. 已知取舍
|
||||
|
||||
- 一键入口可以在内部多次调用模型，特别是非 Ozon 来源的分层类目选择；页面应显示异步进度，不能假设一个同步 HTTP 请求必定快速完成。
|
||||
- 直接回填提高速度，也要求可撤销、保留手填值、版本检查和完整任务记录。当前页面不增加逐项确认步骤。
|
||||
- 目前 `model` 是跨平台商品字段并会成为 Ozon 型号名称。若将来需要「内部编码」与「消费者可见型号」分离，应再增字段和迁移；本期不为此增加隐藏的第二套型号。
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# 商品编辑 API 契约
|
||||
|
||||
> 本文是早期产品级接口草案，部分路径和状态已经被实现契约取代，不应直接作为联调依据。当前端点、平台目录缓存和发布预检以 [`../api/product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 为准；所有请求仍须按当前用户、工作空间和平台/门店上下文授权，客户端不能跨租户指定 ID。浏览器插件采集入口以 [`../requirements/collector-browser-extension.md`](../requirements/collector-browser-extension.md) 为准。
|
||||
> 本文是早期产品级接口草案，部分路径和状态已经被实现契约取代，不应直接作为联调依据。尤其下文的独立 AI 类目/文案接口与逐项人工应用流程已由[统一 AI 填报方案](./ai-autofill-plan.md)取代。当前端点、平台目录缓存和发布预检以 [`../api/product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 为准；所有请求仍须按当前用户、工作空间和平台/门店上下文授权，客户端不能跨租户指定 ID。浏览器插件采集入口以 [`../requirements/collector-browser-extension.md`](../requirements/collector-browser-extension.md) 为准。
|
||||
|
||||
## 1. 采集与读取
|
||||
|
||||
|
||||
@@ -22,11 +22,11 @@ workspaces 1 ── N collection_items ── 0..1 products (SPU) 1 ── N pro
|
||||
（平台发布配置） （平台 SKU 首次发布映射）
|
||||
```
|
||||
|
||||
`collection_items` 是工作空间级采集箱记录，保存来源平台、来源商品键、原始证据、规范化结果、素材任务和可空的草稿商品关联；它在采集阶段没有 `target_platform_id` 或 `target_store_id`。每个父商品至少有一条 SKU。`products` 仅是**采集箱商品**的跨平台可复用资料：来源标题、用户填写的型号、条形码、采买地址、货源备注、默认规格和来源证据；采集阶段型号允许为空，不能从来源数据猜测生成。首次上架前型号必须已由用户确认填写；不把任何一个平台的类目、价格、属性或上架状态直接写到该表。
|
||||
`collection_items` 是工作空间级采集箱记录，保存来源平台、来源商品键、原始证据、规范化结果、素材任务和可空的草稿商品关联；它在采集阶段没有 `target_platform_id` 或 `target_store_id`。每个父商品至少有一条 SKU。`products` 仅是**采集箱商品**的跨平台可复用资料：来源标题、用户手填或主动 AI 填报的型号、条形码、采买地址、货源备注、默认规格和来源证据；采集入箱时型号允许为空，不直接从来源数据猜测填入。首次上架前型号必须非空并通过现有校验；不把任何一个平台的类目、价格、属性或上架状态直接写到该表。
|
||||
|
||||
`product_platform_profiles` 是 `product_id + platform_id` 唯一的平台发布配置。用户在页头选中平台并进入编辑时才创建或读取它；它保存当前目标门店、该平台的标题/简介/标签、类目和类型、平台通用属性及本平台草稿版本。A 平台与 B 平台独立配置、独立状态；A 已上架不会让 B 显示已上架。门店只是配置中可改的当前发布目标，实际每次发布仍会在 SKU 映射中固化当时的 `store_id`。
|
||||
|
||||
`product_variants` 保存：稳定来源键、展示名、删除状态、排序、采购价、SKU 规格、包装物流规格、实物规格和时间戳。`product_variant_platform_listings` 保存平台 SKU 维度的数据：`profile_id`、`variant_id`、用户填写的本平台 `offer_id`（货号）、售价、划线价、币种、平台变体属性、首次导入状态/失败原因、首次导入任务和当时 `store_id`、Ozon `product_id`。采集时不得根据 `source_sku` 自动填入 `offer_id`；用户填写后，它对同一门店/平台连接必须唯一，并且是首次上架的必填项。成功导入的 SKU 映射不可再次创建导入任务；删除 Atlas SKU 只软删 Atlas 关联，不删除平台商品和审计记录。
|
||||
`product_variants` 保存：稳定来源键、展示名、删除状态、排序、采购价、SKU 规格、包装物流规格、实物规格和时间戳。`product_variant_platform_listings` 保存平台 SKU 维度的数据：`profile_id`、`variant_id`、用户填写或主动 AI 填报生成的本平台 `offer_id`（货号）、售价、划线价、币种、平台变体属性、首次导入状态/失败原因、首次导入任务和当时 `store_id`、Ozon `product_id`。AI 填报落地时新增可空的 SKU 发布标题 `title`；`title=null`、`description=null`、`tags=[]` 分别继承 SPU 当前平台发布配置的标题、描述、标签，非空/非空数组则按 SKU 覆盖。`product_variants.display_name` 只是内部展示名，不能充当发布标题。中俄文案对照按 SPU/SKU 作用域保存，继承时读取 SPU 对照而不复制。采集入箱时不填入 `offer_id`；编辑页主动生成或手填后，它对同一门店/平台连接必须唯一，并且是首次上架的必填项。成功导入的 SKU 映射不可再次创建导入任务；删除 Atlas SKU 只软删 Atlas 关联，不删除平台商品和审计记录。
|
||||
|
||||
`platform_listings`（实际建表名待定）保存店铺级在线商品 SKU 镜像，一条记录对应 Ozon 的一个 `product_id` / `offer_id`，而非采集箱 SPU：`store_id`、平台 `product_id`、`offer_id`、平台 SKU、名称、价格、可见性、审核/错误、库存、图片摘要、完整同步快照、最近同步时间和来源（`atlas_published` / `external_sync`）。它是**平台 + 门店独有**的外部事实记录，绝不跨平台、跨门店复用，也不因关联了采集箱 SKU 就变成采集箱商品。它由异步同步任务更新，包含非 Atlas 发布的商品；通过 `store_id + offer_id/product_id` 可选关联 Atlas SKU。采集箱不因成功上架而删除，其当前平台状态由首次导入映射汇总；在线商品的 `visible` 只用于在线商品实际可见性展示。
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ Ozon 商品的必填属性由 `description_category_id` 与 `type_id` 对应的
|
||||
|
||||
### 2.3 SKU 设置
|
||||
|
||||
Ozon schema 中 `is_aspect=true` 的属性放入每个 SKU 卡片的「Ozon 变体属性」区域，不再按 SKU 名称集中堆放在产品属性区。每张 SKU 卡片包含：
|
||||
Ozon schema 中 `is_aspect=true` 的属性放入每个 SKU 卡片展开后的「SKU 信息」区域，与包装和文案字段共用布局，不单独显示「Ozon 变体属性」标题。每张 SKU 卡片包含：
|
||||
|
||||
- SKU 名称与当前平台上架状态；
|
||||
- 卖家货号 `offer_id`；
|
||||
@@ -195,7 +195,7 @@ POST /api/product-platform-profiles/{profile_id}/publish-preflights
|
||||
- 保存草稿允许不完整，发布校验阻断缺失项。
|
||||
- 服务端补齐通用和逐 SKU 必填属性检查。
|
||||
|
||||
实现状态：已完成。编辑器会在选定类目后立即加载 schema，商品级必填属性始终显示在「产品属性」，SKU 级必填属性始终显示在对应 SKU 卡片；保存草稿不因缺少必填值失败，`validation` 接口按商品与 SKU 返回结构化缺失项。
|
||||
实现状态：已完成。编辑器会在选定类目后立即加载 schema，商品级必填属性始终显示在「产品属性」，SKU 级变体属性在对应 SKU 展开后的「SKU 信息」中显示；保存草稿不因缺少必填值失败，`validation` 接口按商品与 SKU 返回结构化缺失项。
|
||||
|
||||
类目 schema 中由编辑器已有控件承载的字段通过 `editor_field` 显式绑定，不在动态属性区重复展示，也不重复加载其字典。绑定只允许按 Ozon 属性 ID：品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254`、简介/产品描述 `4191`；禁止使用名称或翻译文本猜测。后续发布适配器必须据此生成 Ozon 所需字段，不能要求用户重复填写。
|
||||
|
||||
|
||||
@@ -9,15 +9,15 @@
|
||||
```text
|
||||
页头：返回 · 商品标题 · 当前平台 · 目标门店 · 当前平台上架状态 · 来源
|
||||
├─ 主要信息
|
||||
│ ├─ 类目、标题、型号、品牌
|
||||
│ ├─ 类目、中文商品名、俄文发布标题、型号、品牌
|
||||
│ └─ 默认包装重量与默认包装尺寸
|
||||
├─ 产品属性
|
||||
│ ├─ 主题标签、简介、采买地址与货源备注
|
||||
│ └─ 当前平台/市场的商品级动态属性
|
||||
├─ SKU 商品：卡片（默认）/ 紧凑列表
|
||||
│ └─ N 个 SKU；维护货号、条形码、图片、价格、变体属性及可选包装覆盖
|
||||
│ └─ N 个 SKU；维护货号、条形码、图片、价格、变体属性、三项 SKU 文案及可选包装覆盖
|
||||
└─ 固定操作栏
|
||||
├─ 左：AI 类目 · AI 标题/标签/描述 · AI 套图生成
|
||||
├─ 左：AI 填报 · AI 套图生成
|
||||
└─ 右：取消并关闭 · 保存草稿 · 选择未上架 SKU 并首次上架
|
||||
```
|
||||
|
||||
@@ -25,7 +25,9 @@
|
||||
|
||||
页面以编辑草稿工作，不采用字段失焦即写库。保存草稿需原子提交父商品、SKU、属性和媒体顺序；存在未保存修改时关闭页面须二次确认。SKU 定价确认是例外：它会即时持久化该 SKU 的价格与定价快照。
|
||||
|
||||
采集进入采集箱时，商品**型号**和各 SKU 的目标平台**货号（Ozon `offer_id`）**默认都为空，不从来源标题、来源 SKU 或规格名称猜测生成。用户在编辑页填写：型号属于商品通用资料；货号属于当前平台下的每个 SKU。两者允许随草稿保存而暂时为空，但首次上架校验必须全部通过：商品型号非空，且每个待上架 SKU 的货号非空并在目标店铺内唯一。
|
||||
主要信息中的“中文商品名”用于 Atlas 内部识别；“俄文发布标题”是 SPU 共用发布标题，页面保存时必须填写。AI 填报仍可从俄文标题为空的采集草稿启动；发布前服务端会再次检查该字段。
|
||||
|
||||
采集进入采集箱时，商品**型号**和各 SKU 的目标平台**货号（Ozon `offer_id`）**默认都为空。进入编辑页后，用户可手动填写或点击“AI 填报”生成并直接填入表单；生成货号不直接照搬来源 SKU。型号属于商品通用资料，货号属于当前平台下的每个 SKU。两者允许随草稿保存而暂时为空，但首次上架校验必须全部通过：商品型号非空，且每个待上架 SKU 的货号非空并在目标店铺内唯一。详见[AI 填报方案](./ai-autofill-plan.md)。
|
||||
|
||||
上架状态是“当前平台 + SKU”维度：`未上架`、`处理中`、`上架失败`、`已上架`。SPU 在当前平台的状态由未删除 SKU 汇总为 `未上架`、`已部分上架`、`已上架`。用户可勾选任意未上架 SKU 执行首次上架；已上架 SKU 不显示上架选择，也不发送更新请求。编辑已上架 SKU 时，保存按钮旁必须提示“仅保存 Atlas 草稿，不会更新 Ozon 商品”。
|
||||
|
||||
@@ -39,9 +41,9 @@
|
||||
|
||||
## 3. SKU 卡片和列表
|
||||
|
||||
卡片默认展示：序号、SKU 名称、当前平台上架状态、最多 3 张图片缩略图（可切换为 5）、货号、条形码、采购价、售价、划线价、定价按钮、按 schema 展示的商品规格与 Ozon 变体属性。列表仅是紧凑视图，字段和数据完全相同。货号由用户填写，不自动复用来源 SKU；缺少货号的 SKU 可保存但不能被选择首次上架。SKU 包装规格为空时继承主要信息中的默认包装规格；只有该 SKU 包装不同才填写覆盖值。商品净重和商品尺寸不是 Ozon 固定物流字段，只在当前 schema 的对应属性为 SKU 级（`is_aspect=true`）时展示；商品级属性继续在 SPU 展示。首期不支持视频上传、编辑或发布；视频能力待 Ozon 对应接口和审核规则确定后再开启。
|
||||
卡片默认展示：序号、SKU 名称、当前平台上架状态、最多 3 张图片缩略图（可切换为 5）、货号、条形码、采购价、售价、划线价、定价按钮、按 schema 展示的商品规格与 Ozon 变体属性。列表仅是紧凑视图，字段和数据完全相同。货号可由用户填写或“AI 填报”生成，不直接复用来源 SKU；缺少货号的 SKU 可保存但不能被选择首次上架。SKU 包装规格为空时继承主要信息中的默认包装规格；只有该 SKU 包装不同才填写覆盖值。商品净重和商品尺寸不是 Ozon 固定物流字段，只在当前 schema 的对应属性为 SKU 级（`is_aspect=true`）时展示；商品级属性继续在 SPU 展示。首期不支持视频上传、编辑或发布；视频能力待 Ozon 对应接口和审核规则确定后再开启。
|
||||
|
||||
SKU 名称只用于展示；采集 SKU 用稳定 `source_variant_key` 关联，手工 SKU 用本地 UUID。规格字段 `null` 仅表示没有覆盖父商品默认值，绝不能据此判断是否单规格或缺少 SKU。
|
||||
SKU 名称只用于展示，不是发布标题；采集 SKU 用稳定 `source_variant_key` 关联，手工 SKU 用本地 UUID。SKU 展开区提供发布标题、主题标签、产品描述；留空逐字段继承 SPU，手工输入或应用当前 SKU 的 AI 结果才覆盖该项。SPU 三项旁的加号只显示对应 SKU 输入框，不复制共用文案。规格字段 `null` 仅表示没有覆盖父商品默认值，绝不能据此判断是否单规格或缺少 SKU。
|
||||
|
||||
无论 SPU 或 SKU 在当前平台是否已上架，用户都可以新增 SKU 变体、复制任一既有 SKU 作为新变体、删除 SKU。复制出的 SKU 没有平台发布映射，始终从 `未上架` 开始。删除已上架 SKU 只从 Atlas 商品结构和当前平台的可发布 SKU 集合移除，**不会删除、下架或修改 Ozon 已创建的商品**；删除未上架 SKU 后若当前平台只剩已上架 SKU，SPU 状态变为 `已上架`。
|
||||
|
||||
@@ -65,6 +67,6 @@ SKU 图片编辑弹窗左侧是该 SKU 的已选图片（排序/移除），右
|
||||
|
||||
首期素材规则：发布图片仅接受 JPG、PNG、WebP；单文件最大 20 MB，最短边低于 700 px 给出警告且不得作为主图，超过 10,000 px 的边长在上传时拒绝；建议 1:1 或 3:4，允许其他比例但在预览中提示裁切风险。采集候选素材可保留原始文件供编辑选择，实际发布时始终按目标平台的图片数、格式和可访问性校验。Ozon 发布图片必须是可由 Ozon 拉取的 HTTPS 地址。
|
||||
|
||||
AI 文案针对当前平台的商品信息生成候选标题、标签与简介，用户选择后写入草稿；首期不生成或编辑富内容。AI 套图由左侧抽屉承载，必须显式选择目标 SKU；尺寸图一 SKU 一任务，并保存实物规格快照。
|
||||
“AI 填报”针对当前平台一次生成类目、型号、SKU 货号、证据充分的包装规格以及 **SPU 共用的**标题、标签与简介，并在任务完成后直接填入当前页面表单，等待用户保存。SKU 文案默认继承 SPU；用户可从当前 SKU 的 AI 图标单独生成并在弹窗明确应用。SPU 和每个 SKU 的三项字段旁均有「中文对照」图标，打开同一个弹窗查看当前作用域左俄右中的三项对照；继承字段标明来源，俄文被手改后该字段对照标为待更新。首期不生成或编辑富内容。AI 套图由左侧抽屉承载，必须显式选择目标 SKU；尺寸图一 SKU 一任务，并保存实物规格快照。
|
||||
|
||||
AI 类目由用户主动触发：系统将采集标题、规格、参数、图片摘要等证据与当前平台可发布的类目树交给 AI，返回候选类目、置信度和简短依据，用户必须选择确认后才写入当前平台发布配置。来源为 Ozon 的商品优先保留采集到的 Ozon 类目，默认不自动调用 AI，但始终允许用户主动重新推荐；1688、淘宝、天猫等其他来源默认提供“AI 推荐类目”以提升上品速度。AI 不得直接自动落类目或跳过类目属性校验。
|
||||
类目推荐由“AI 填报”主动触发：系统将采集证据与当前平台可发布的类目候选交给 AI。Ozon 来源优先沿用现有确定性匹配；1688、淘宝、天猫等来源由 AI 评估目标类目。服务端验证候选 UUID 后可将明确结果填入**未保存的页面表单**；用户点击保存后才写入平台发布配置。歧义结果留给用户选择。AI 不得跳过类目属性校验；本期 AI 填报不处理动态类目属性。
|
||||
|
||||
+32
-13
@@ -1,24 +1,24 @@
|
||||
# Atlas Seller Kit 交接说明
|
||||
|
||||
> 更新：2026-09-10。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md)。
|
||||
> 更新：2026-09-23。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md) 和仓库 `AGENTS.md`。下方按日期记录的旧方案仅供追溯；当前状态以本节及 [1.39](#139-开发进度与交接2026-09-23商品-ai-填报与编辑页收口) 为准。
|
||||
|
||||
## 1. 项目定位
|
||||
|
||||
这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
|
||||
|
||||
当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店、水印/素材、采集箱与扩展采集入库；Worker 已具备 Ozon 凭据验证、采集记录清理和按需来源素材转存消费链路，仓库同步尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理、真实采集箱页面和采集数据测试页；浏览器扩展已提供毛子 ERP 风格的网页登录态同步、悬浮窗及 Ozon/1688/淘宝/天猫首版页面状态解析。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。
|
||||
pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享契约、数据库包和本地基础设施。认证、工作空间隔离、门店/素材、采集箱、商品编辑草稿、平台级商品参考目录、发布预检和商品 AI 填报已有实现；真正的 Ozon 首次发布、在线商品同步和定价确认仍未形成完整闭环。不要从旧项目复制 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)。
|
||||
|
||||
## 0. 交接结论（先看这里）
|
||||
|
||||
当前已经完成的是“采集 → 采集箱 → 商品编辑草稿”的主要数据闭环，以及 M3.0–M3.4 商品领域基础、编辑器核心、AI 来源素材字段级合并、动态属性和缓存同步基础。数据库迁移、工作空间隔离、同商品归属外键、幂等键和 product/profile 双乐观锁已经落地。
|
||||
已完成“采集 → 采集箱 → 商品编辑草稿”的主要数据闭环、平台级类目/属性/字典目录与发布预检。编辑页已接入异步「AI 填报」：基于来源资料与 Atlas 类目树生成类目建议、型号/SKU 货号、证据充分的包装建议及 SPU 中俄文案；单 SKU 文案由用户单独生成并确认应用。AI 结果只回填未保存表单，保存草稿仍是持久化边界。Ozon 动态类目属性可按已选类目加载并手工填写，**当前不由 AI 自动填报**。
|
||||
|
||||
当前没有完成的是“可直接用于发布”的闭环：候选素材已经可以选择、转存并保存为 SKU 的平台素材，但定价确认、AI 任务与候选结果、Ozon 首次发布、在线商品同步仍未开发。真实站点回归也尚未由本项目完成；用户已确认此前提出的首次回归项基本满足采集箱和商品编辑需求，但仍建议在最终发布前保留一轮样本验收。
|
||||
尚未完成可直接发布的闭环：定价确认、真正的 Ozon 发布 job/import 及结果轮询、在线商品同步仍待开发。AI 类目推荐和文案已能运行，但不能等同于跨来源样本验收；尤其应继续用 1688/淘宝/天猫样本核验 Atlas 类目候选质量，以及俄文文案、包装证据和 SKU 继承行为。AI 生图仍是占位入口。
|
||||
|
||||
当前最高优先级是以真实来源样本回归素材转存与选择，然后进入定价确认能力。类目树改造已落地：Worker 使用显式指定的 Ozon 缓存源预热共享树，编辑器直接读取 Cascader 树，并会在空类目时按 Ozon 来源层级回填；详见 [1.28](#128-开发进度2026-09-10类目树预热与来源回填)。
|
||||
当前优先事项：用真实来源样本回归 AI 类目推荐、文案与候选素材；完成定价确认；让首次发布 job 复用既有发布预检，再实现 Ozon import 与结果轮询。平台参考目录目前由平台级参考源和同步任务维护，不能把 9 月 10 日的门店级缓存描述当作现行架构。
|
||||
|
||||
接手前请先阅读 `git status --short`；当前 M3 商品编辑和 M3.4/M3.5 缓存改动均已提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。
|
||||
接手前请先阅读 `git status --short`；截至本次更新，AI 填报涉及 API、Worker、Web、contracts、迁移和文档的改动仍在工作区，其中若干文件未跟踪，不能当作已提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。开发验证需要时可按 `AGENTS.md` 先确认进程与端口，再启动或重启 API/Worker；下方旧章节中的“不可重启”说法已失效。
|
||||
|
||||
### 1.1 开发进度（2026-09-02）
|
||||
|
||||
@@ -427,6 +427,25 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
|
||||
- 管理页面的缓存新鲜度设置由按钮打开弹窗；最近任务手动刷新有 loading 及成功/失败 message，5 秒自动轮询静默执行。
|
||||
- 旧门店目录章节保留为带日期的历史实现记录，不代表当前读写路径。当前未完成重点是真正的 Ozon 发布 job、树级发布新鲜度边界、大字典续传以及平台目录 PostgreSQL 集成测试。
|
||||
|
||||
### 1.39 开发进度与交接（2026-09-23）：商品 AI 填报与编辑页收口
|
||||
|
||||
**已实现的链路**
|
||||
|
||||
- `029_product_ai_autofill.sql` 定义 AI 任务、中俄对照与 SKU 可空发布标题；API 提供全局填报、单 SKU 文案任务和任务状态读取。API 在工作空间事务内固化输入快照、写任务与 Outbox；Worker 从 `DEEPSEEK_API_KEY`、`DEEPSEEK_MODEL_NAME` 读取配置调用 DeepSeek。任务不直接写商品草稿，页面在完成后核对商品、profile 和来源快照版本，再把合格结果填入未保存表单。API、Worker、Web 与共享类型均有对应代码；迁移是否已应用到当前目标数据库，本次文档更新未核验。
|
||||
- 全局填报读取 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 Prompt：`title.ru`、`tags[].ru`、`description.ru` 不得出现汉字；来源中文事实应翻译为自然俄文，只有有依据的拉丁品牌/型号及阿拉伯数字可保留。Worker 结果校验会丢弃仍含汉字的对应字段，中文对照与包装原文证据不受此限制。旧已保存文案不会自动改写，需重新生成或手工修订。
|
||||
|
||||
**验证状态与下一步**
|
||||
|
||||
- 最近一轮俄文禁汉字改动已通过 Worker `product-ai.test.mjs` 7 项测试、Worker TypeScript 检查和 `git diff --check`；本次交接文档更新未再发起真实 DeepSeek 请求。其他页面/API 变更有此前的构建及集成测试记录，但不能视为本次对整个脏工作区的重新验收。
|
||||
- 下一步先核对目标环境的 `029`/`030` 迁移与 API/Worker 当前进程版本，再使用 Ozon、1688、淘宝、天猫各类样本回归：类目候选准确性与确认、中文来源到纯俄文输出、无包装证据、多个 SKU 的共用型号与独立货号、SPU/SKU 文案继承和保存后中文对照。重点复查此前 1688 类目不足提示与 DeepSeek 失败场景；不能仅以单元测试认定质量已稳定。
|
||||
- 之后继续定价确认、素材按需物化回归、平台目录大字典续传与管理员回归，并将真正的首次发布 job 接到现有发布预检。发布预检 `ready` 不是已上架；在线商品同步也尚未实现。
|
||||
|
||||
详细字段规则与任务接口见 [`ai-autofill-plan.md`](../product/ai-autofill-plan.md) 和 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md)。
|
||||
|
||||
## 2. 已确认产品决策
|
||||
|
||||
| 主题 | 决策 |
|
||||
@@ -435,7 +454,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
|
||||
| 平台可售单元 | 一个 SKU 对应一个独立平台 offer；Ozon 首个平台中对应 `/v3/product/import.items[]` 的一项和独立 `offer_id`。 |
|
||||
| 通用属性 | 标题、品牌、型号、主题标签、简介、条形码、采买地址、货源备注及未来商品级属性；类目和平台属性属于独立的平台发布配置。首期不做富内容。 |
|
||||
| SKU 属性 | SKU 名称、图片、货号、采购价、售价、划线价、包装重量和尺寸、商品重量和尺寸、商品颜色、颜色名称等。首期不支持视频。 |
|
||||
| 型号/货号 | 型号（`model`）是父商品通用字段；`offer_id` 是当前平台下的每个 SKU 字段。采集时两者可为空；首次上架前必须由用户填写，系统不从标题、规格或来源 SKU 自动生成。被成功导入的 `offer_id` 作为历史事实锁定。 |
|
||||
| 型号/货号 | 型号（`model`）是父商品通用字段；`offer_id` 是当前平台下的每个 SKU 字段。采集入箱时两者可为空；编辑页可手填，也可在用户主动点击“AI 填报”后生成并填入表单，保存和发布时仍校验唯一性。被成功导入的 `offer_id` 作为历史事实锁定。详见[AI 填报方案](../product/ai-autofill-plan.md)。 |
|
||||
| 规格 | 实物规格与包装物流规格严格分离；尺寸图只读取实物规格，计价/物流/发布只读取包装规格。 |
|
||||
| 继承 | 可继承字段的 `null` 表示该字段没有覆盖父商品默认值，不表示 SKU 不存在、名称为空或商品为单规格。 |
|
||||
| 尺寸图 | 必须逐 SKU 生成，任务保存 SKU ID 和实物规格快照。 |
|
||||
@@ -474,13 +493,13 @@ User → Workspace → Membership / Role
|
||||
|
||||
## 5. 已冻结的第一阶段 API 契约
|
||||
|
||||
第一阶段 HTTP API 的接口范围已讨论完成，当前状态为**设计冻结、部分业务接口已实现**。认证、平台目录/上下文、创建/查询/编辑/默认/删除门店、异步操作读取及仓库摘要读取已有实现与集成测试；门店凭据验证、仓库同步的实际平台调用仍待 Worker 消费 Outbox 后完成。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源；旧 [`product/api.md`](../product/api.md) 仅作历史背景，不能作为实现依据。
|
||||
第一阶段 HTTP API 的接口范围已讨论完成，当前状态为**设计冻结、分模块实施**。认证、门店、采集、商品编辑、平台参考目录、发布预检与 AI 任务已有接口和实现；定价、真正的商品发布及在线商品同步仍未形成完整接口/Worker 闭环。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源；旧 [`product/api.md`](../product/api.md) 仅作历史背景，不能作为实现依据。
|
||||
|
||||
- 覆盖账户认证、平台/门店、水印与素材、定价、浏览器采集/采集箱、商品编辑/首次发布、在线商品读取与同步。
|
||||
- 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`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 凭据验证 Worker、上传意图清理 Worker、采集记录清理 Worker 与来源素材转存 Worker 均已实现。仓库同步、发布和在线商品同步 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)。
|
||||
|
||||
@@ -490,11 +509,11 @@ User → Workspace → Membership / Role
|
||||
|
||||
> 注意：下面的清单不能覆盖 2026-09-18 的 [Ozon 参考目录决策](../architecture/platform-product-reference-catalog.md)。平台目录、后台、同步基础链路和商品编辑器迁移已经实现；旧门店目录只作为兼容/回滚数据保留。
|
||||
|
||||
当前执行顺序：
|
||||
当前执行顺序（2026-09-23）：
|
||||
|
||||
1. 将真正的 `publish-jobs` 创建事务接入已经完成的发布预检服务，固化发布快照后再实现 Ozon `/v3/product/import` 与结果轮询；不得重新实现另一套目录判断。
|
||||
2. 完成平台目录首次预热并修正大字典续传；补系统管理员浏览器回归。旧门店目录继续保留，暂不清理。
|
||||
3. 在真实采集来源中继续回归候选媒体按需物化，然后完成定价、AI 任务、首次发布和在线商品同步的剩余纵向闭环。
|
||||
1. 核对 AI 任务迁移、运行进程版本和四类来源的真实样本；回归类目选择、中俄文案（俄文字段不含汉字）、包装证据、SKU 文案继承及候选媒体按需物化。
|
||||
2. 完成定价确认、平台目录大字典续传与管理员浏览器回归；旧门店目录继续保留，暂不清理。
|
||||
3. 将真正的 `publish-jobs` 创建事务接入已完成的发布预检，固化发布快照后实现 Ozon `/v3/product/import` 与结果轮询，再推进在线商品同步；不得重新实现另一套目录判断。
|
||||
|
||||
### 历史计划（仅供追溯）
|
||||
|
||||
|
||||
@@ -23,15 +23,15 @@
|
||||
|
||||
### 2. `offer_id`（Ozon 货号）策略
|
||||
|
||||
**状态：已决策，待接口和数据校验落地。**
|
||||
**状态：2026-09-22 修订决策；AI 填报尚未实现。**
|
||||
|
||||
- 采集进入采集箱时，型号（`model`）和 `offer_id` 都允许为空。
|
||||
- 用户在商品编辑页填写：`model` 是商品通用字段；`offer_id` 是当前平台下、每个 SKU 的字段。
|
||||
- 系统**不**从采集标题、规格或来源 SKU 自动生成 `offer_id`。
|
||||
- 首次上架前，`model` 必填；每个被选中 SKU 的 `offer_id` 必填，且在目标门店内唯一。
|
||||
- `model` 是商品通用字段；`offer_id` 是当前平台下、每个 SKU 的字段。用户可手动填写，也可在进入编辑页后点击“AI 填报”，由规则与 AI 生成并直接填入表单。
|
||||
- 采集入箱本身不填写货号；AI 生成以 Atlas 稳定商品标识、已确认类目和实际 SKU 规格为依据，可使用来源信息提炼语义片段，但不得直接复用来源 SKU 作为目标平台货号。
|
||||
- 首次上架前，`model` 必填；每个被选中 SKU 的 `offer_id` 必填，且在目标门店内唯一。生成值和手填值接受相同的保存及发布校验。
|
||||
- 导入成功后，该次平台 SKU 发布记录使用的 `offer_id` 作为历史事实，不允许通过“重新上架”改变；后续编辑在线商品属于另一套平台商品更新能力。
|
||||
|
||||
`docs/api/product-editor-and-publishing.md`、商品域 DDL 和发布前校验必须以本节为准，不再保留“自动生成可编辑货号”的备选逻辑。
|
||||
详细的主动生成、表单回填及冲突处理见 [`../product/ai-autofill-plan.md`](../product/ai-autofill-plan.md)。
|
||||
|
||||
## P1：实现对应模块前修正
|
||||
|
||||
|
||||
Reference in New Issue
Block a user