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

docs: 更新文档

Browse Source
This commit is contained in:
R524809
2026-09-20 15:23:44 +08:00
parent 880e441bc6
commit e0e07be4ea
19 changed files with 164 additions and 312 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/product/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 商品 AI 编辑页
> 状态：已确认的产品需求与领域设计，尚未实施。它是 Atlas Seller Kit 的商品工作流规范。
> 状态：商品编辑主流程和 Ozon 动态属性 P0 已实施，平台类目/属性/字典读取及首次发布预检已迁移完成；定价确认、AI 任务和真正调用 Ozon 的发布 job 仍有未实施部分。准确接口状态以 [`../api/product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 和 [`../project/HANDOFF.md`](../project/HANDOFF.md) 为准。
## 目标
docs/product/api.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 商品编辑 API 契约
> 接口前缀与鉴权细节待基础架构确认。所有请求由当前用户、工作空间、门店上下文授权；客户端不能跨租户指定 ID。浏览器插件采集入口以 [`../requirements/collector-browser-extension.md`](../requirements/collector-browser-extension.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. 采集与读取
docs/product/ozon-dynamic-attributes-and-sku-form-plan.md
+31 -17
View File
@@ -1,10 +1,10 @@
# Ozon 动态属性与 SKU 填报改造方案
> 状态：P0 已于 2026-09-18 实现，P1/P2 待实施。当前已完成必填展示、通用/变体属性分区、宽松草稿保存及服务端逐 SKU 校验；新 SKU 首次保存时关联属性、结构化字典值与发布闭环仍以后续阶段为准。
> 状态：P0 已于 2026-09-18 实现，平台目录读取和首次发布预检已于 2026-09-20 迁移到平台级缓存；P1 与真正调用 Ozon 的发布 job 待实施。当前已完成必填展示、通用/变体属性分区、宽松草稿保存、服务端逐 SKU 校验和发布前定向刷新；新 SKU 首次保存时关联属性、结构化字典值、发布快照与 Ozon 错误回填仍以后续阶段为准。
## 1. 目标与原则
Ozon 商品的必填属性由 `description_category_id` 与 `type_id` 对应的类目 schema 决定；同一 Ozon 平台的所有门店共用该 schema。编辑器不得为儿童玩具、服装、食品等类目分别硬编码字段，而应使用 Ozon 返回的 `is_required`、`is_aspect`、`dictionary_id`、`is_collection`、`max_value_count`、`type` 与复杂属性信息驱动展示、填报和发布校验。当前编辑器已经读取平台级类目、属性和字典缓存；发布链路迁移仍待后续步骤。
Ozon 商品的必填属性由 `description_category_id` 与 `type_id` 对应的类目 schema 决定；同一 Ozon 平台的所有门店共用该 schema。编辑器不得为儿童玩具、服装、食品等类目分别硬编码字段，而应使用 Ozon 返回的 `is_required`、`is_aspect`、`dictionary_id`、`is_collection`、`max_value_count`、`type` 与复杂属性信息驱动展示、填报和发布校验。当前编辑器和首次发布预检均读取平台级类目、属性和字典缓存；真正创建发布 job 并调用 Ozon 的闭环仍待后续实现。
页面继续以 Atlas 商品和 SKU 为编辑主体：主要信息保留稳定的商品级字段，Ozon 类目属性按通用属性和 SKU 变体属性拆分。保存草稿允许信息不完整；首次上架必须由服务端按当时有效的类目 schema 重新校验。
@@ -58,35 +58,41 @@ SKU 中的 Ozon 必填变体属性同样只在 Label 前显示红色 `*`。父
## 3. Schema 获取与展示状态
选择目标门店和末级类目后，系统使用门店缓存记录中的 `description_category_id + type_id` 获取属性 schema：
选择末级类目后，系统使用平台目录中的 `description_category_id + type_id` 获取属性 schema：
1. 优先读取当前门店的本地 schema 缓存。
2. 缓存不存在或超过约定有效期时，创建异步同步任务并显示「正在更新 Ozon 类目要求」。
3. 同步成功后重新构建动态属性表单。
4. 页面显示类目路径、商品类型和最后同步时间，并提供失败后的重试入口。
1. 优先读取当前平台共享的 Atlas schema 缓存；切换同平台目标门店不改变目录。
2. fresh 直接返回；stale（默认 14～21 天，含 21 天）返回旧缓存并创建/复用低优先级 Worker 任务。
3. expired（严格超过 21 天）或 missing 时创建/复用高优先级任务，API 最多等待 5 秒；仍未完成则返回 `202` 和 cache 元数据，前端轮询后重建表单。
4. 字典值使用 schema 返回的 Atlas `attribute_id` 精确限定平台、类型和属性作用域；部分字典的关键词未命中使用独立 `dictionary_search` 缓存状态。
5. 页面显示类目路径、商品类型和缓存状态，并提供失败后的重试入口。所有 Ozon 请求由 Worker 使用平台参考源凭据执行，浏览器和 API 进程不直连 Ozon。
以上描述当前门店级 schema 的获取流程。迁移到平台级参考目录后，直接读取当前平台共享 schema，不叠加门店差异；普通用户只请求 Atlas，Atlas 在缓存 stale、expired 或 missing 时创建/复用统一 Worker 任务，不由 API 进程直连 Ozon。14～21 天的旧缓存立即返回并低优先级刷新，严格超过 21 天或未缓存时等待高优先级任务；完整规则见[平台目录缓存刷新方案](../architecture/platform-catalog-cache-refresh-plan.md)。接口字段及草稿外键在 `docs/api/` 更新前不改变。
属性 schema 响应除现有字段外，计划补充：
完整规则见[平台目录缓存刷新方案](../architecture/platform-catalog-cache-refresh-plan.md)。当前属性 schema 契约为：
```ts
type ProductAttributeSchema = {
attribute_id: string;
platform_attribute_id: string;
complex_id: string;
name: string;
description: string | null;
group_id: string | null;
group_name: string | null;
value_type: 'text' | 'integer' | 'decimal' | 'boolean' | 'dictionary';
is_required: boolean;
is_collection: boolean;
max_value_count: number;
dictionary_id: string | null;
is_aspect: boolean;
synced_at: string;
editor_field:
| 'category'
| 'brand'
| 'model'
| 'tags'
| 'rich_content'
| 'description'
| null;
};
```
响应外层同时返回 `cache.status`、`last_success_at`、`fresh_until`、`expires_at`、完整性、刷新任务和重试间隔。`editor_field` 只按 Ozon 属性 ID 绑定已有编辑器字段，不按名称或翻译文本猜测。
切换类目后，新 schema 中仍可匹配的值可以保留；不再匹配的旧属性进入未映射属性区，不能进入新的发布 payload，也不应仅由前端直接清空而丢失。
## 4. 属性值表达
@@ -103,7 +109,7 @@ type ProductAttributeValue =
- 字典属性根据缓存中的 `dictionary_value_id` 解析对应显示值，不能信任客户端伪造的字典名称。
- 自由输入属性写入文本值，并按 Ozon 请求格式设置相应的空字典标识。
- 服务端校验字典值属于当前门店、当前类目和当前属性。
- 服务端校验字典值属于当前平台、当前类目类型和当前属性；门店不参与参考字典归属。
- 属性值数量、类型和复杂属性结构均由服务端复核。
## 5. 新增 SKU 与属性契约
@@ -138,7 +144,7 @@ SKU 条形码应保存到当前平台 listing 维度；现有商品级条形码
### 6.2 首次上架
实现并复用统一的服务端发布就绪校验：
本地草稿就绪校验使用：
```text
GET /api/product-platform-profiles/{profile_id}/validation
@@ -156,6 +162,14 @@ GET /api/product-platform-profiles/{profile_id}/validation
`POST /publish-jobs` 必须调用同一套校验，不能信任浏览器校验结果。保存草稿和创建发布任务应继续保持各自的事务与幂等边界。
真正创建发布 job 前还必须调用已实现的：
```text
POST /api/product-platform-profiles/{profile_id}/publish-preflights
```
预检只处理用户选中的 `not_listed` / `failed` SKU，按当前平台类型 schema 和实际使用的字典执行 fresh/stale/expired/missing 判断：stale 使用旧缓存并低优先级刷新，expired/missing 高优先级刷新且所有任务共享一个 5 秒等待窗口。目录可用后再执行统一本地校验；返回 `ready` 才能进入未来的发布快照事务。当前预检尚未检查整棵类目树的新鲜度，只验证 profile 引用的本地类目仍活动；真正发布 job 接入前需要补齐或确认这一边界。
## 7. Ozon 发布错误回填
本地 schema 无法覆盖 Ozon 所有条件校验。Ozon 拒绝某个 import item 时，系统应：
@@ -191,7 +205,7 @@ GET /api/product-platform-profiles/{profile_id}/validation
### P2：发布闭环
- 发布接口复用现有 validation 校验结果。
- 发布前定向刷新与 validation 复用已通过 `publish-preflights` 完成；真正发布接口必须调用同一服务。
- 按 SKU 生成 `/v3/product/import` 的 `items[]`。
- 正确生成普通属性与复杂属性。
- 固化发布快照并将 Ozon 错误回填到 SKU/属性。
docs/product/product-ai-editor.md
+5 -1
View File
@@ -29,7 +29,11 @@
上架状态是“当前平台 + SKU”维度：`未上架`、`处理中`、`上架失败`、`已上架`。SPU 在当前平台的状态由未删除 SKU 汇总为 `未上架`、`已部分上架`、`已上架`。用户可勾选任意未上架 SKU 执行首次上架；已上架 SKU 不显示上架选择，也不发送更新请求。编辑已上架 SKU 时，保存按钮旁必须提示“仅保存 Atlas 草稿，不会更新 Ozon 商品”。
当前实现中，前端根据目标门店的本地类目 schema 渲染属性控件、必填提示、字典选择、多值限制及变体属性。门店 Ozon 凭据验证成功后，Worker 使用该门店凭据同步中文类目树；缓存为空时编辑器显示准备中状态，用户不能在编辑页发起树同步。选中类目但 schema 缺失时，仍可显式同步该类目属性。字典控件先搜索本地缓存，输入至少两个字符仍无结果时，可显式从 Ozon 搜索并缓存命中值。`is_aspect=true` 在编辑器中按 SKU 展示，其余属性按商品展示；保存仍由服务端复核 schema 与字典值。选择类目和属性与商品草稿同一次保存，`platform_type_id` 从服务端门店类目缓存取得。类目变更或 schema 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。[待迁移目标](../architecture/platform-product-reference-catalog.md)是同平台门店共用参考目录，本阶段不维护门店差异层。
当前实现中，类目/商品类型树、类型属性和字典候选值均读取当前平台的共享参考目录，不再按目标门店复制；同平台切换门店不会清空或重新同步目录。平台参考源凭据仅由系统管理员配置，所有 Ozon 请求经 Worker 执行，浏览器和 API 进程都不直连 Ozon。
前端按平台 schema 渲染必填提示、字典选择、多值限制及变体属性。`is_aspect=true` 按 SKU 展示，其余属性按商品展示；品牌、型号、类型、主题标签、JSON 富内容和简介等已有编辑器字段严格按 Ozon 属性 ID 绑定，不在动态属性区重复出现。类型属性和字典默认 14 天内 fresh，14～21 天（含边界）stale 时继续返回旧缓存并低优先级刷新，严格超过 21 天或从未同步时创建高优先级任务、最多等待 5 秒，未完成则返回 `202` 并由前端轮询。类目树固定每 7 天自动同步，也可由系统管理员手动同步。
保存仍由服务端按平台 schema 与字典值复核。选择类目和属性与商品草稿同一次保存，`platform_type_id` 从平台类目记录取得；类目变更或 schema 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。首次发布前已提供 `publish-preflights` 复用同一套目录新鲜度与本地校验逻辑；真正创建发布任务并调用 Ozon 的流程尚未实现。完整规则见[平台目录缓存刷新方案](../architecture/platform-catalog-cache-refresh-plan.md)。
类目、标题、型号、品牌以及默认包装重量和默认包装尺寸固定放在「主要信息」区。SKU 默认继承父商品包装规格，仅在包装不同的情况下填写覆盖值。平台动态必填字段统一使用表单标准表现，在 Label 前显示红色 `*`；不追加「Ozon 必填」标签，也不在区块标题显示完成数量。更完整的目标交互、属性值表达、SKU 关联和发布校验改造见 [`ozon-dynamic-attributes-and-sku-form-plan.md`](./ozon-dynamic-attributes-and-sku-form-plan.md)。