feat(category): 类目树、属性、属性字典维护，新增系统管理员管理类目数据
This commit is contained in:
R524809
+98
-8
@@ -215,7 +215,7 @@
|
||||
|
||||
### 1.25 开发进度（2026-09-10）：M3.4 类目与动态属性
|
||||
|
||||
- 旧迁移 `021_product_category_attribute_schema.sql` 建立了平台级 schema 缓存；最新设计由 `022_store_catalog_cache.sql` 另建门店级类目、schema 与字典缓存，发布草稿只引用门店级数据。
|
||||
- 旧迁移 `021_product_category_attribute_schema.sql` 建立了平台级 schema 缓存；当时采用 `022_store_catalog_cache.sql` 另建门店级类目、schema 与字典缓存，发布草稿只引用门店级数据。此处记录已实现历史，2026-09-18 的新目标见[平台级参考目录决策](../architecture/platform-product-reference-catalog.md)。
|
||||
- 新增编辑器接口：类目候选、类目属性 schema 与属性字典值。类目 schema/字典接口支持传入未保存的 `category_id` 预览，因此用户选择新类目后不必先保存一次才能填写字段。
|
||||
- 编辑器草稿可原子保存 `store_product_category_id`、类目来源与商品/SKU 属性；服务端派生 `platform_type_id`，复核类型、值数量、字典值与 SKU 归属。类目变更或 schema 下线的旧属性会转入 `product_unmapped_attributes`，不会默默丢失或进入新的发布 payload。
|
||||
- Web 编辑页已提供类目选择、商品/SKU 维度动态字段、字典选择、未映射属性告警；上架店铺/主题标签保持标准 40px 控件高度，父商品包装重量与三项包装尺寸宽度分别为 150px / 120px。
|
||||
@@ -224,17 +224,18 @@
|
||||
|
||||
- 已实现类目树、类目属性 schema、字典值缓存的数据表、Worker 同步逻辑、Transactional Outbox 和读 API；缓存属于门店级发布元数据，不属于某个商品草稿。浏览器、operation 响应与 outbox 事件都不含 API Key。
|
||||
- 当前旧实现仍把“同步 Ozon 类目”暴露为商品编辑页操作；这已被最新产品决策否定，不能作为完成状态使用。属性 schema 仍是按类目读取/按需同步的现状，后续需单独确认是否也改为启动预热。
|
||||
- 字典不会全量拉取：字段先读取已有缓存；用户输入至少两个字符且本地无匹配时，现有实现可显式发起 Ozon `/attribute/values/search`，Worker 仅 upsert 返回的命中项。同步失败应保留旧缓存和可读错误状态。
|
||||
- 字典不会全量拉取：字段先读取已有缓存；首次打开某个字典属性时，按需从 Ozon `/attribute/values` 按游标同步首批最多 1000 项，当前类目下同一字典仅自动触发一次。输入至少两个字符后延迟调用 Ozon `/attribute/values/search`，补充首批以外的候选；本地缓存每页返回 200 项并支持下拉滚动续读。同步失败应保留旧缓存和可读错误状态。
|
||||
|
||||
### 1.27 历史状态（2026-09-10）：平台级预热方案已废弃
|
||||
|
||||
- 原交接要求的“Worker 启动时以指定门店预热一份平台共享类目树”已被产品决策替代：类目、属性和字典缓存按门店隔离，不能再恢复平台级共享缓存或环境变量指定的共享源。
|
||||
- 原交接要求的“Worker 启动时以指定门店预热一份平台共享类目树”当时被门店级方案替代。该时期要求类目、属性和字典按门店隔离，不恢复平台级共享缓存或以环境变量任意指定客户门店作为共享源。
|
||||
- 保留的原则是：浏览器、日志、operation 和 outbox 事件均不携带 API Key；编辑器只读缓存，不提供类目树手动同步入口。
|
||||
- 本节只记录当时决策；2026-09-18 的[平台级参考目录决策](../architecture/platform-product-reference-catalog.md)已取代该目标。现有门店级实现未随文档决策自动迁移。
|
||||
|
||||
### 1.28 开发进度（2026-09-10）：门店类目同步与来源回填
|
||||
|
||||
- Ozon 门店凭据验证成功后，在同一事务中创建门店类目同步 operation 与 outbox 事件；Worker 使用该门店 `Client-Id + Api-Key` 请求中文类目树，并写入 `store_product_categories`。失败只标记类目同步 operation，不会把已验证的凭据改为无效。
|
||||
- 已删除编辑器的手动类目树同步接口和客户端调用。属性 schema 与字典值仍按当前类目和关键词按需同步，使用原有 Outbox/Worker 链路。
|
||||
- 已删除编辑器的手动类目树同步接口和客户端调用。属性 schema 与字典值仍按当前类目按需同步；字典支持打开控件时同步首批值和按关键词搜索，均使用原有 Outbox/Worker 链路。
|
||||
- Cascader 显示完整缓存树路径，但表单与草稿 API 始终保存末级类目 UUID，修复了路径数组不能直接提交到 `editor-draft` 的问题。
|
||||
- 对 Ozon 来源商品，进入或读取编辑器时会将 `common.categories` 的规范化层级路径与活动缓存节点精确匹配；仅当 profile 未保存类目时写入匹配项并标记 `source_capture`。已有手工选择或此前保存的类目永远不被复采覆盖。API 集成测试覆盖回填和保护规则。
|
||||
- 已新增 API 集成测试覆盖来源回填和保护规则；仍需在有效 Ozon 门店、真实 Ozon 样本与浏览器页面上执行最终回归。本地 Docker 基础设施未启动时，该集成测试无法实际执行。
|
||||
@@ -275,6 +276,93 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目
|
||||
|
||||
下一步：在真实采集来源中回归首次按需物化、Worker 下载失败重试与已选图片保存；然后实施定价确认。来源域限流、429/503 延迟重试和跨候选 URL 下载去重属于 Worker 下载器的后续可靠性加固，尚未在本 M3.6 变更中完成。
|
||||
|
||||
### 1.32 开发进度（2026-09-18）：Ozon 动态属性与 SKU 表单 P0
|
||||
|
||||
- 编辑器选择类目后立即加载属性 schema。`is_required=true` 的商品级属性始终展示在「产品属性」，`is_aspect=true` 的必填属性始终展示在对应 SKU 卡片；必填状态仅使用 Label 前的红色 `*`，选填属性仍可折叠。
|
||||
- 动态属性控件已拆为独立组件，统一处理字典、布尔、数值、文本和多值字段；商品级与 SKU 级属性只负责各自的分区编排。主要信息继续保留类目、标题、型号、品牌和默认包装规格，SKU 展开区可覆盖包装及商品规格。
|
||||
- 草稿保存不会因 Ozon 必填属性或包装规格为空而失败；已提交的非空属性仍由 API 校验类型、数量、字典归属、类目归属及 `is_aspect` 对应的商品/SKU scope。
|
||||
- 新增 `GET /api/product-platform-profiles/{profile_id}/validation`，在独立校验模块中返回商品级问题和逐 SKU 问题。已导入 SKU 标为 `not_publishable_again`；必填通用属性和必填变体属性都以当前门店类目 schema 为准。
|
||||
- 类目 schema 新增 `editor_field` 语义绑定，严格按 Ozon 属性 ID 识别品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254` 和简介/产品描述 `4191`。这些字段由编辑器已有控件承载，动态属性区不再重复展示或预取字典；名称和翻译文本不参与判断。
|
||||
- Contracts、API 与 Web TypeScript 检查、Web production build 和 `git diff --check` 已通过。API 集成测试已补充通用/逐 SKU 必填缺失和 scope 伪造场景；本轮环境无法连接 PostgreSQL/Redis，因此未实际跑通该集成测试，且未按约定启动 API 或 Worker。
|
||||
|
||||
后续 P1/P2 仍包括：新 SKU 通过 `client_key` 在首次保存时关联动态属性、SKU 级条形码、结构化字典值，以及首次发布任务复用 validation 并回填 Ozon 错误。详见 [`ozon-dynamic-attributes-and-sku-form-plan.md`](../product/ozon-dynamic-attributes-and-sku-form-plan.md)。
|
||||
|
||||
### 1.33 开发进度与交接（2026-09-18）：平台级商品参考目录、系统后台与同步维护
|
||||
|
||||
#### 1.33.1 已冻结的数据归属
|
||||
|
||||
- 类目/商品类型树、类型属性定义和字典候选值归属 `platform_id`，同一平台的全部门店共用，不再按门店复制。Ozon 与未来 Wildberries 等平台分别使用自己的适配器和外部 ID 语义；本阶段**不创建、不读取门店差异层**。
|
||||
- 门店连接、卖家凭据、商品/SKU 已填属性、发布状态和错误仍是工作空间业务数据。平台参考目录不保存客户商品、价格、库存或发布事实。
|
||||
- 这项平台级能力已经独立落地，但商品编辑器仍使用 `022_store_catalog_cache.sql` 的门店级类目 UUID、属性和字典 API。不得直接删除旧表或把新旧 UUID 混用；编辑器迁移必须通过 Ozon 外部 ID 做双读/回填后再切换。
|
||||
|
||||
#### 1.33.2 类目树、属性和字典的标识规则
|
||||
|
||||
| 参考数据 | Atlas 表与唯一作用域 | Ozon 字段及处理规则 |
|
||||
|---|---|---|
|
||||
| 类目/类型树 | `platform_product_categories`；`platform_id + external_category_id + external_type_id` | `external_category_id = description_category_id`，`external_type_id = type_id`。类型节点可能不重复返回类目 ID，映射器会继承最近父类目的 `description_category_id`。纯目录节点使用 `type_id = 0`，只用于树结构，不允许作为建品类型；可发布类型必须同时使用 `description_category_id + type_id`，不能按名称或单独 ID 匹配。`parent_id` 和 `path` 由树同步统一重建，Ozon `disabled` 或本次全量树中消失的节点标为非活动，不物理删除。 |
|
||||
| 类型属性定义 | `platform_product_category_attributes`；平台 + 类型节点 + `platform_attribute_id + complex_id` | 保存 Ozon 属性 `id`、`attribute_complex_id/complex_id`、名称、说明、分组、类型、`is_required`、`is_aspect`、`is_collection`、`max_value_count`、`dictionary_id` 和 `category_dependent`。属性同步是某一 `description_category_id + type_id` 的完整定义；成功后本次未返回的旧属性标为非活动。 |
|
||||
| 字典候选值 | `platform_catalog_dictionary_values`；`attribute_id + external_value_id` | 调用字典接口时必须同时传 `attribute_id + description_category_id + type_id`。即使 Ozon 返回相同 `dictionary_id`，也不能只按字典 ID 跨类型合并。当前每页 2000 项，单任务最多读取 5 页；不足 5 页且 `has_next=false` 才记录 `is_complete=true`，只有完整同步才停用本次未返回的旧值。 |
|
||||
|
||||
商品编辑器隐藏品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254`、简介/产品描述 `4191` 时，仍严格使用 Ozon 属性 ID；名称只用于展示。管理后台是参考数据检查工具，会展示完整属性定义，不应用编辑器的隐藏规则。
|
||||
|
||||
#### 1.33.3 数据库和安全边界
|
||||
|
||||
迁移 `024_platform_catalog_management.sql` 已新增或扩展以下对象：
|
||||
|
||||
- `system_admin_grants`：独立的全局系统管理员授权。工作空间 `owner/admin` 不等于系统管理员；`atlas_app` 被撤销该表的写权限，不能通过普通 HTTP 接口自助提权。
|
||||
- `platform_catalog_sources`：每个平台一份专用参考源。Ozon `Api-Key` 使用现有 AES-256-GCM 边界加密，随机 nonce 与不可逆 HMAC fingerprint 分开保存；响应只返回脱敏 Client-Id，不回显密钥、密文或 fingerprint。
|
||||
- `platform_catalog_dictionary_values`：替代旧平台字典表不足以表达类目/属性作用域的问题；旧表暂不删除。
|
||||
- `platform_catalog_sync_runs`：平台级树、属性和字典任务事实，记录触发方式、状态、来源版本、尝试次数、结果数量和脱敏错误。
|
||||
- `platform_catalog_sync_requests`：把系统管理员的 `Idempotency-Key` 持久映射到任务；即使手动请求复用了一个已存在的定时任务，重试也不会在原任务完成后创建第二个任务。
|
||||
- `platform_catalog_outbox_events`：不带 `workspace_id` 的平台级 Transactional Outbox。平台任务不能借用租户 `operations/outbox_events`，避免伪造工作空间归属。
|
||||
|
||||
配置来源时，API 在同一事务更新密文和 `revision`，取消旧来源尚未完成的任务，并排队一次树同步。Worker 在领取和提交结果时都会比较 `source_revision`；来源已经更换的旧任务只能取消，不能用新凭据执行或覆盖新数据。API Key 只在 API 加密入口和 Worker 解密调用 Ozon 的短暂内存中出现，不进入浏览器回显、任务载荷或日志。
|
||||
|
||||
#### 1.33.4 系统管理员后台
|
||||
|
||||
- 独立后台路由为 `/system/platform-catalog`，布局不依赖工作台的门店选择器。普通登录用户可调用 `GET /api/system/access` 获取布尔值；所有管理读写 API 还会在服务端实时校验 `system_admin_grants`，前端隐藏菜单不是权限边界。
|
||||
- 页面名称为「平台类目与属性」。可选择平台、查看参考源状态和类目树最近成功时间；选择可发布类型后查看属性 ID、必填、SKU 变体、数据类型及已缓存候选值数量；字典在 Drawer 中分页搜索 Atlas 缓存并显示完整/部分状态。
|
||||
- 「配置同步来源」提交 Client-Id 与 Api-Key。首次配置或实际变更会自动排队树同步；重复提交同一凭据不增加来源版本或重复任务。
|
||||
- 「同步类目树」「同步当前类型属性」「同步此字典」都只向 API 排队，不在 HTTP 请求中直接访问 Ozon。最近任务表每 5 秒轮询一次；任务由 `queued → running → succeeded/failed/cancelled` 转换，完成后页面重新读取相应缓存。
|
||||
- 管理 API 契约、首位管理员初始化 SQL 和错误边界见 [`platform-catalog-admin.md`](../api/platform-catalog-admin.md)。目前数据库已经存在一名有效系统管理员授权；此前反馈过用户菜单没有显示入口，数据库授权已确认正确，但刷新/当前 Web 与 API 进程版本下的菜单展示仍需浏览器回归。
|
||||
|
||||
#### 1.33.5 手动同步与自动同步的共同链路
|
||||
|
||||
```text
|
||||
系统管理员页面 / 定时调度器
|
||||
↓ 同一事务创建 run + platform outbox
|
||||
PlatformCatalogDispatcher（每 2 秒，批量最多 20 条）
|
||||
↓ 投递 atlas-dispatch / platform_catalog_sync.requested
|
||||
BullMQ Worker（最多 5 次，5 秒起指数退避）
|
||||
↓ 使用平台参考源凭据调用 Ozon
|
||||
事务内 upsert 参考数据并完成 run
|
||||
↓
|
||||
管理页面轮询任务并重新读取 Atlas 缓存
|
||||
```
|
||||
|
||||
- 手动接口要求 UUID `Idempotency-Key`。同一平台和 `scope_key` 只允许一个 `queued/running` 任务；已有活动任务时返回并映射到该任务。
|
||||
- Worker 启动时立即执行一次调度，之后每 60 秒扫描一次。每个平台最多保留 6 个活动任务，优先级依次为树、属性、字典；树和属性成功后 24 小时内不重复，字典成功后 7 天内不重复，任一作用域创建任务后 1 小时内不会被定时器重复排队。
|
||||
- Ozon 单次 HTTP 超时为 30 秒。401/403 转换为凭据错误；429、5xx、网络错误和响应结构异常交给 BullMQ 重试；其他确定性 4xx 直接记录请求被拒绝。最终失败只更新任务错误，不清空上次成功缓存。
|
||||
- 树、某类型的属性和某属性的字典分别在单个数据库事务中发布。读取方在事务提交前仍看到旧缓存；P0 尚未实现不可变版本快照、内容哈希和 `next_refresh_at`，当前依赖事务 upsert、`synced_at` 与任务历史保证一致性和可追踪性。
|
||||
|
||||
#### 1.33.6 当前实际进度快照
|
||||
|
||||
- `024_platform_catalog_management.sql` 已于 2026-09-18 实际应用，系统管理员授权已写入并回读验证。
|
||||
- Worker 曾因先于 `024` 迁移启动而无法初始化平台 Outbox Dispatcher；迁移后 Worker 已恢复。最新数据库事实显示 Outbox 已被分发、任务 `attempt_count=1`，证明平台 Dispatcher、BullMQ 消费和 Ozon 调用链路当前正在工作。
|
||||
- 两次 Ozon 类目树任务均已成功，每次映射结果为 7933 条；当前活动节点为 7365 条，差额主要是纯目录/禁用节点。定时属性预热已经开始：检查时 18 个属性任务成功，当前活动属性定义 436 条，单类型返回约 27～50 个属性。
|
||||
- 字典候选值当前仍为 0，尚未进入有效的初始预热阶段。现有调度固定优先全部属性，再处理字典；在数千个类型下可能导致字典长期排在属性之后，这是已知的 P0 调度公平性问题，不能把“属性同步已开始”误认为字典已经可供全部用户使用。
|
||||
- 已通过 API/Worker/Web TypeScript 检查、Web production build、3 项系统管理员/参数单元测试、6 项 Ozon 树/属性/字典映射与分页测试及 `git diff --check`。由于功能落地后才执行迁移，尚未新增并运行覆盖真实 PostgreSQL 的平台目录端到端测试；现有成功任务提供了真实 Ozon 链路验证，但不能替代自动化数据库回归。
|
||||
|
||||
#### 1.33.7 明确未完成项
|
||||
|
||||
1. 调整定时调度公平性：树之后不能等待全部类型属性完成才开始字典；应在属性和字典之间设置配额/轮转，并优先近期使用或管理员选中的类型。
|
||||
2. 为超过 10000 项的大字典实现可续传游标或分片同步周期。当前任务会正确标记 `is_complete=false`，但下一次仍从头读取，不能持续推进到第 10001 项以后。
|
||||
3. 将商品编辑器由门店级缓存迁移到平台级目录：按 `description_category_id + type_id` 和属性 ID 回填，先双读/兼容保存，再切换外键和 API，最后才讨论清理 `022` 表。
|
||||
4. 增加平台目录 PostgreSQL 集成测试，覆盖系统管理员隔离、凭据版本替换、手动幂等复用、定时去重、失败保留旧缓存、完整字典停用旧值及跨平台 ID 拒绝。
|
||||
5. 在浏览器完成管理员菜单、直达路由、凭据弹窗、任务轮询、类目/属性/字典展示的回归，并确认 API/Worker 进程都使用迁移后的当前代码。
|
||||
|
||||
完整架构边界见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)，HTTP 契约见 [`platform-catalog-admin.md`](../api/platform-catalog-admin.md)。
|
||||
|
||||
## 2. 已确认产品决策
|
||||
|
||||
| 主题 | 决策 |
|
||||
@@ -293,6 +381,7 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目
|
||||
| 采集 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` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面和手动排队已实现；商品编辑器的门店级引用待迁移，见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)。 |
|
||||
|
||||
## 3. Ozon 已核对结论
|
||||
|
||||
@@ -335,13 +424,13 @@ User → Workspace → Membership / Role
|
||||
|
||||
下一步建议按以下顺序推进：
|
||||
|
||||
> 注意：下面的历史清单仍保留用于追溯；当前执行优先级以 [`1.27 当前进行中`](#127-当前进行中2026-09-10类目树交互改造尚未验收) 和本段补充为准。先完成类目启动同步、树形选择与 Ozon 来源类目自动回填，再进入真实采集回归和后续发布能力。
|
||||
> 注意：下面的清单不能覆盖 2026-09-18 的 [Ozon 参考目录决策](../architecture/platform-product-reference-catalog.md)。平台目录、后台和同步基础链路已经实现；现有门店级商品编辑契约在完成兼容迁移前继续生效。
|
||||
|
||||
当前执行顺序：
|
||||
|
||||
1. 配置专用 Ozon 类目缓存源，在真实 Ozon 样本和 8100 页面完成类目预热、树形选择及来源回填回归。
|
||||
2. 完成候选媒体选择与按需物化，并把已选素材纳入 SKU 编辑草稿。
|
||||
3. 完成定价、AI 任务与候选结果、首次发布和在线商品同步的剩余纵向闭环。
|
||||
1. 完成平台目录首次预热并修正属性/字典调度公平性和大字典续传；补 PostgreSQL 集成测试与系统管理员浏览器回归。
|
||||
2. 按 Ozon 外部 ID 建立新旧目录映射和双读，迁移商品编辑器到平台级类目、属性和候选值；在验证前保留门店级缓存与外键。
|
||||
3. 在真实采集来源中继续回归候选媒体按需物化，然后完成定价、AI 任务、首次发布和在线商品同步的剩余纵向闭环。
|
||||
|
||||
### 历史计划（仅供追溯）
|
||||
|
||||
@@ -360,6 +449,7 @@ User → Workspace → Membership / Role
|
||||
- [API 统一约定](../api/conventions.md)
|
||||
- [基础模块数据模型与 DDL](../architecture/foundation-data-model.md)
|
||||
- [商品领域数据模型与 DDL](../architecture/product-domain-data-model.md)
|
||||
- [平台级商品参考目录决策](../architecture/platform-product-reference-catalog.md)
|
||||
- [幂等与 Transactional Outbox](../architecture/transactional-outbox-and-idempotency.md)
|
||||
- [数据库角色与 RLS](../architecture/database-security.md)
|
||||
- [商品采集图片与存储策略](../architecture/media-storage-strategy.md)
|
||||
|
||||
Reference in New Issue
Block a user