feat(category): 类目树、属性、属性字典维护，新增系统管理员管理类目数据

2026-09-18 18:55:16 +08:00
parent fcddb11da0
commit 388429dbd0
58 changed files with 4347 additions and 640 deletions
@@ -1,10 +1,10 @@
 # Ozon 动态属性与 SKU 填报改造方案

-> 状态：待实施设计，记录于 2026-09-18。本文描述目标交互、数据归属和校验边界；在对应 API 契约、共享类型与实现完成更新前，不代表当前接口已经具备这些行为。
+> 状态：P0 已于 2026-09-18 实现，P1/P2 待实施。当前已完成必填展示、通用/变体属性分区、宽松草稿保存及服务端逐 SKU 校验；新 SKU 首次保存时关联属性、结构化字典值与发布闭环仍以后续阶段为准。

 ## 1. 目标与原则

-Ozon 商品的必填属性由目标门店、`description_category_id` 与 `type_id` 对应的实时类目 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` 与复杂属性信息驱动展示、填报和发布校验。目标参考数据归属见[架构决策](../architecture/platform-product-reference-catalog.md)；当前实现仍读门店级缓存。

 页面继续以 Atlas 商品和 SKU 为编辑主体：主要信息保留稳定的商品级字段，Ozon 类目属性按通用属性和 SKU 变体属性拆分。保存草稿允许信息不完整；首次上架必须由服务端按当时有效的类目 schema 重新校验。

@@ -65,6 +65,8 @@ SKU 中的 Ozon 必填变体属性同样只在 Label 前显示红色 `*`。父
 3. 同步成功后重新构建动态属性表单。
 4. 页面显示类目路径、商品类型和最后同步时间，并提供失败后的重试入口。

+以上描述当前门店级 schema 的获取流程。迁移到平台级参考目录后，直接读取当前平台共享 schema，不叠加门店差异；缺失或过期时由统一后台任务补齐，普通用户不直接触发 Ozon 请求，管理员重试与定时任务共用同一队列。接口字段及草稿外键在 `docs/api/` 更新前不改变。
+
 属性 schema 响应除现有字段外，计划补充：

 ```ts
@@ -175,6 +177,10 @@ GET /api/product-platform-profiles/{profile_id}/validation
 - 保存草稿允许不完整，发布校验阻断缺失项。
 - 服务端补齐通用和逐 SKU 必填属性检查。

+实现状态：已完成。编辑器会在选定类目后立即加载 schema，商品级必填属性始终显示在「产品属性」，SKU 级必填属性始终显示在对应 SKU 卡片；保存草稿不因缺少必填值失败，`validation` 接口按商品与 SKU 返回结构化缺失项。
+
+类目 schema 中由编辑器已有控件承载的字段通过 `editor_field` 显式绑定，不在动态属性区重复展示，也不重复加载其字典。绑定只允许按 Ozon 属性 ID：品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254`、简介/产品描述 `4191`；禁止使用名称或翻译文本猜测。后续发布适配器必须据此生成 Ozon 所需字段，不能要求用户重复填写。
+
 ### P1：SKU 数据结构

 - 属性草稿调整为 `common_attributes + variants[].attributes`。
@@ -185,7 +191,7 @@ GET /api/product-platform-profiles/{profile_id}/validation

 ### P2：发布闭环

- 实现 validation 接口及发布接口复用。
+- 发布接口复用现有 validation 校验结果。
 - 按 SKU 生成 `/v3/product/import` 的 `items[]`。
 - 正确生成普通属性与复杂属性。
 - 固化发布快照并将 Ozon 错误回填到 SKU/属性。
@@ -29,7 +29,7 @@

 上架状态是“当前平台 + SKU”维度：`未上架`、`处理中`、`上架失败`、`已上架`。SPU 在当前平台的状态由未删除 SKU 汇总为 `未上架`、`已部分上架`、`已上架`。用户可勾选任意未上架 SKU 执行首次上架；已上架 SKU 不显示上架选择，也不发送更新请求。编辑已上架 SKU 时，保存按钮旁必须提示“仅保存 Atlas 草稿，不会更新 Ozon 商品”。

-前端根据当前目标门店、本地同步的商品类目 schema 渲染属性控件、必填提示、字典选择、多值限制及变体属性。门店 Ozon 凭据验证成功后，Worker 使用该门店凭据同步中文类目树；缓存为空时编辑器显示准备中状态，用户不能在编辑页发起树同步。选中类目但 schema 缺失时，仍可显式同步该类目属性。字典控件先搜索本地缓存，输入至少两个字符仍无结果时，可显式从 Ozon 搜索并缓存命中值。`is_aspect=true` 在编辑器中按 SKU 展示，其余属性按商品展示；保存仍由服务端复核 schema 与字典值。选择类目和属性与商品草稿同一次保存，`platform_type_id` 从服务端门店类目缓存取得。类目变更或 schema 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。
+当前实现中，前端根据目标门店的本地类目 schema 渲染属性控件、必填提示、字典选择、多值限制及变体属性。门店 Ozon 凭据验证成功后，Worker 使用该门店凭据同步中文类目树；缓存为空时编辑器显示准备中状态，用户不能在编辑页发起树同步。选中类目但 schema 缺失时，仍可显式同步该类目属性。字典控件先搜索本地缓存，输入至少两个字符仍无结果时，可显式从 Ozon 搜索并缓存命中值。`is_aspect=true` 在编辑器中按 SKU 展示，其余属性按商品展示；保存仍由服务端复核 schema 与字典值。选择类目和属性与商品草稿同一次保存，`platform_type_id` 从服务端门店类目缓存取得。类目变更或 schema 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。[待迁移目标](../architecture/platform-product-reference-catalog.md)是同平台门店共用参考目录，本阶段不维护门店差异层。

 类目、标题、型号、品牌以及默认包装重量和默认包装尺寸固定放在「主要信息」区。SKU 默认继承父商品包装规格，仅在包装不同的情况下填写覆盖值。平台动态必填字段统一使用表单标准表现，在 Label 前显示红色 `*`；不追加「Ozon 必填」标签，也不在区块标题显示完成数量。更完整的目标交互、属性值表达、SKU 关联和发布校验改造见 [`ozon-dynamic-attributes-and-sku-form-plan.md`](./ozon-dynamic-attributes-and-sku-form-plan.md)。