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/属性。