feat(edit): 编辑页类目树逻辑开发

2026-09-10 22:26:52 +08:00
parent 946af649dd
commit 05a00d46b9
13 changed files with 628 additions and 323 deletions
@@ -1,6 +1,6 @@
 # 商品编辑与首次上架 API

-> M3.0 已实现第 1 节的 `POST /editor-contexts` 和 `GET /editor` 基础读模型，以及对应数据库归属约束。M3.1 已实现产品基础字段、当前平台文案、SKU 与 `offer_id` 的原子草稿保存及双版本并发控制。M3.2 已实现目标店铺候选与切换语义、父/子 SKU 的实物/包装规格继承、规格轴、SKU 复制和当前上架状态读模型。M3.3/M3.3.1 已实现 AI 来源素材的字段级合并、原子保存、复采变化提示与 AI 输入读模型。M3.4 已实现本地类目候选、动态属性 schema/字典、属性草稿与类目切换后的未映射保留。M3.5 已通过 Worker 同步 Ozon 类目树，并按类目/关键词按需同步 schema 和字典缓存；媒体选择、定价、AI 任务与发布仍是冻结契约，尚未实现。
+> M3.0 已实现第 1 节的 `POST /editor-contexts` 和 `GET /editor` 基础读模型，以及对应数据库归属约束。M3.1 已实现产品基础字段、当前平台文案、SKU 与 `offer_id` 的原子草稿保存及双版本并发控制。M3.2 已实现目标店铺候选与切换语义、父/子 SKU 的实物/包装规格继承、规格轴、SKU 复制和当前上架状态读模型。M3.3/M3.3.1 已实现 AI 来源素材的字段级合并、原子保存、复采变化提示与 AI 输入读模型。M3.4 已实现本地类目候选、动态属性 schema/字典、属性草稿与类目切换后的未映射保留。M3.5 在门店 Ozon 凭据验证成功后同步该门店的中文类目树，编辑器只读取当前目标门店缓存；属性和关键词字典仍按需同步。媒体选择、定价、AI 任务与发布仍是冻结契约，尚未实现。

 > 此处的商品始终是采集箱内的 Atlas 草稿。所有平台范围接口要求 `X-Atlas-Platform-Id`。商品通用资料可以跨平台复用；`product_platform_profile`、SKU 首次导入状态和在线商品不能跨平台/门店复用。

@@ -92,7 +92,7 @@ Headers：`If-Match: "{product_revision}:{profile_revision}"`、`Idempotency-Key
    "default_physical_spec": { "length_mm": "100", "width_mm": "50", "height_mm": "20", "net_weight_g": "300", "status": "confirmed" },
    "default_package_spec": { "length_mm": "120", "width_mm": "60", "height_mm": "30", "shipping_weight_g": "400", "status": "confirmed" } },
  "profile": { "target_store_id": "uuid", "fulfillment": "rfbs", "title": "Название", "description": "…", "tags": ["tag"],
-    "platform_product_category_id": "uuid", "category_source": "manual" },
+    "store_product_category_id": "uuid", "category_source": "manual" },
  "variants": [{
    "id": "uuid-or-null", "client_key": "new-row-key", "copy_from_variant_id": null, "display_name": "黑色 / M", "source_sku": null,
    "specification_values": [{ "axis_key": "color", "value_key": "black", "value_name": "黑色" }], "purchase_cost_cny": "80.00",
@@ -110,7 +110,7 @@ Headers：`If-Match: "{product_revision}:{profile_revision}"`、`Idempotency-Key
 - `ai_source_material` 是客户端当前看到的完整有效素材，`ai_source_overridden_fields` 仅列出用户明确修改的顶层字段。服务端只持久化这些字段的覆盖值，其余字段继续跟随最新采集结果；恢复字段时将其从该数组移除即可。
 - 来源素材与商品/SKU 草稿在同一事务保存，受 `product.revision` 保护。`ai_source_material.source_snapshot_revision` 必须等于服务端当前采集版本；保存期间发生复采时返回 `409 SOURCE_SNAPSHOT_CHANGED`，客户端应重新读取合并结果并让用户确认，不能用旧页面覆盖新来源。
 - 保存来源素材不会修改原始采集证据。`ai_source_overridden_fields` 只允许 `title`、`description`、`price`、`brand`、`attributes`、`categories`，且每项按完整顶层值覆盖，不做数组或对象内部的隐式合并。
- `profile.platform_product_category_id` 必须是当前平台的活动类目；服务端从类目记录取得 `platform_type_id`，客户端不能伪造类型 ID。`attributes` 是完整属性草稿集合，属性 ID、复杂属性 ID、值类型、单/多值上限和字典值均由当前类目 schema 校验。
+- `profile.store_product_category_id` 必须是当前目标门店的活动类目；服务端从门店类目记录取得 `platform_type_id`，客户端不能伪造类型 ID。`attributes` 是完整属性草稿集合，属性 ID、复杂属性 ID、值类型、单/多值上限和字典值均由当前门店类目 schema 校验。
 - 类目切换或平台 schema 移除属性时，原有不再适用的属性不会进入新的发布草稿；服务端将它们写入 `unmapped_attributes` 并在编辑快照中返回。用户删除 SKU 时，其 SKU 属性随 SKU 一起移除，不生成无主未映射属性。
 - `variants` 是当前完整未删除 SKU 集合。省略既有 SKU 表示软删除；无论当前 SPU 状态都允许新增、复制、删除。`copy_from_variant_id` 仅用于新行，复制通用 SKU 数据但不复制任何平台导入映射，生成的新 SKU 从 `not_listed` 开始。
 - 删除已导入 SKU 只从 Atlas 草稿及当前平台可发布集合移除，**不删除、不下架、不修改** Ozon 商品或在线镜像；其他平台历史映射保留。删除后当前平台只剩已导入 SKU 时，SPU 汇总自然为“已上架”。
@@ -138,19 +138,15 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": "

 `GET /api/product-platform-profiles/{profile_id}/category-options?q={keyword}`

-返回当前平台最多 100 个活动类目，包含本地 UUID、平台外部类目/类型 ID、名称与路径。选择类目本身不立即写库，随下一次 `editor-draft` 原子保存。
-
-`POST /api/product-platform-profiles/{profile_id}/category-syncs`
-
-请求目标门店的已验证 Seller API 凭据同步 Ozon 类目树，返回 `202` 与 `platform_category_tree_sync` operation。Worker 将树写入全局平台缓存；密钥仅在 Worker 内存中解密，outbox 与响应均不包含密钥。
+返回当前平台的缓存类目树节点，包含本地 UUID、父节点 UUID、平台外部类目/类型 ID、名称、路径和活动状态。选择类目本身不立即写库，随下一次 `editor-draft` 原子保存。缓存为空时客户端显示“准备中”，不提供同步按钮；Worker 仅使用显式配置的共享 Ozon 缓存源预热该树。

 `POST /api/product-platform-profiles/{profile_id}/attribute-schema-syncs?category_id={uuid}`

-为已选活动类目创建 `platform_category_attribute_sync` operation。同步以单类目事务替换 schema；下一次编辑草稿保存会依最新 schema 校验并将不匹配旧值转为未映射草稿。
+为已选门店活动类目创建 `store_category_attribute_sync` operation。同步以单类目事务替换该门店 schema；下一次编辑草稿保存会依最新 schema 校验并将不匹配旧值转为未映射草稿。

 `POST /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{dictionary_id}/syncs?category_id={uuid}&q={keyword}`

-按关键词（至少两个字符）创建 `platform_attribute_dictionary_sync` operation，Worker 使用 Ozon 字典搜索接口并 upsert 命中的本地值。不会为打开一个字段而全量下载大字典；前端先读本地缓存，缺少结果时由用户明确选择“从 Ozon 搜索”。
+按关键词（至少两个字符）创建 `store_attribute_dictionary_sync` operation，Worker 使用该门店的 Ozon 字典搜索接口并 upsert 命中的本地值。不会为打开一个字段而全量下载大字典；前端先读本地缓存，缺少结果时由用户明确选择“从 Ozon 搜索”。

 `GET /api/product-platform-profiles/{profile_id}/validation`

@@ -101,13 +101,13 @@
 ④ 选中后保存 description_category_id + type_id
 ```

-### 场景 2：服务端缓存
+### 场景 2：服务端门店缓存

 ```
-① 启动时拉取类目树（language=DEFAULT，英文字段名便于代码处理）
-② 存入 category_tree 表（见 docs/v2/database.md §2.7）
-③ TTL 24h，过期重拉
-④ 用户选类目时直接查库，不频繁调 API
+① 门店 `Client-Id` + `Api-Key` 验证成功后拉取类目树（Atlas 使用 `ZH_HANS`）
+② 按门店存入本地类目缓存；不与其他门店混用
+③ 同步失败由后台任务重试，已验证的门店凭据不因此改为无效
+④ 用户选类目时直接查当前目标门店缓存，不频繁调 API
 ```

 ---
@@ -27,7 +27,7 @@

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

-前端根据当前平台、本地同步的商品类目 schema 渲染属性控件、必填提示、字典选择、多值限制及变体属性。类目列表为空时，用户可从编辑页发起一次 Ozon 类目树同步；选中类目但 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 下线后，失配属性保留为未映射草稿，不能自动进入发布请求。

 ## 3. SKU 卡片和列表

@@ -16,9 +16,9 @@

 当前没有完成的是“可直接用于发布”的闭环：候选素材选择/物化、定价确认、AI 任务与候选结果、Ozon 首次发布、在线商品同步仍未开发。真实站点回归也尚未由本项目完成；用户已确认此前提出的首次回归项基本满足采集箱和商品编辑需求，但仍建议在最终发布前保留一轮样本验收。

-当前最高优先级是类目行为改造：旧代码仍允许用户手动同步 Ozon 类目，最新决定要求改为应用启动后同步一次并写入数据库，编辑器使用树形 Cascader 直接读取缓存；Ozon 采集到的类目还需要按层级路径自动回填，且不能覆盖用户已经保存的类目。该项目前处于代码改造中，未完成端到端验收，详见 [1.27](#127-当前进行中2026-09-10类目树交互改造尚未验收)。
+当前最高优先级是完成真实样本回归，然后进入候选素材选择/物化这一条发布前纵向能力。类目树改造已落地：Worker 使用显式指定的 Ozon 缓存源预热共享树，编辑器直接读取 Cascader 树，并会在空类目时按 Ozon 来源层级回填；详见 [1.28](#128-开发进度2026-09-10类目树预热与来源回填)。

-接手前请注意：工作区存在未提交的 M3 商品编辑、M3.4/M3.5 缓存、前端样式和迁移改动。不要用 `git reset --hard` 或批量清理未跟踪文件；先阅读 `git status --short`，按文件和迁移编号判断归属。当前中间代码的共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。
+接手前请先阅读 `git status --short`；当前 M3 商品编辑和 M3.4/M3.5 缓存改动均已提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。

 ### 1.1 开发进度（2026-09-02）

@@ -215,24 +215,47 @@

 ### 1.25 开发进度（2026-09-10）：M3.4 类目与动态属性

- 新增迁移 `021_product_category_attribute_schema.sql`，建立平台级的类目属性 schema 与字典值缓存表。缓存记录属性值类型、必填、多值上限、字典标识及 `is_aspect`；它们不是工作空间草稿，商品属性只能引用当前平台/类目的有效 schema。
+- 旧迁移 `021_product_category_attribute_schema.sql` 建立了平台级 schema 缓存；最新设计由 `022_store_catalog_cache.sql` 另建门店级类目、schema 与字典缓存，发布草稿只引用门店级数据。
 - 新增编辑器接口：类目候选、类目属性 schema 与属性字典值。类目 schema/字典接口支持传入未保存的 `category_id` 预览，因此用户选择新类目后不必先保存一次才能填写字段。
- 编辑器草稿可原子保存 `platform_product_category_id`、类目来源与商品/SKU 属性；服务端派生 `platform_type_id`，复核类型、值数量、字典值与 SKU 归属。类目变更或 schema 下线的旧属性会转入 `product_unmapped_attributes`，不会默默丢失或进入新的发布 payload。
+- 编辑器草稿可原子保存 `store_product_category_id`、类目来源与商品/SKU 属性；服务端派生 `platform_type_id`，复核类型、值数量、字典值与 SKU 归属。类目变更或 schema 下线的旧属性会转入 `product_unmapped_attributes`，不会默默丢失或进入新的发布 payload。
 - Web 编辑页已提供类目选择、商品/SKU 维度动态字段、字典选择、未映射属性告警；上架店铺/主题标签保持标准 40px 控件高度，父商品包装重量与三项包装尺寸宽度分别为 150px / 120px。

 ### 1.26 开发进度（2026-09-10）：M3.5 Ozon 类目与属性缓存同步

- 已实现类目树、类目属性 schema、字典值缓存的数据表、Worker 同步逻辑、Transactional Outbox 和读 API；缓存属于平台级元数据，不属于某个商品草稿。浏览器、operation 响应与 outbox 事件都不含 API Key。
+- 已实现类目树、类目属性 schema、字典值缓存的数据表、Worker 同步逻辑、Transactional Outbox 和读 API；缓存属于门店级发布元数据，不属于某个商品草稿。浏览器、operation 响应与 outbox 事件都不含 API Key。
 - 当前旧实现仍把“同步 Ozon 类目”暴露为商品编辑页操作；这已被最新产品决策否定，不能作为完成状态使用。属性 schema 仍是按类目读取/按需同步的现状，后续需单独确认是否也改为启动预热。
 - 字典不会全量拉取：字段先读取已有缓存；用户输入至少两个字符且本地无匹配时，现有实现可显式发起 Ozon `/attribute/values/search`，Worker 仅 upsert 返回的命中项。同步失败应保留旧缓存和可读错误状态。

-### 1.27 当前进行中（2026-09-10）：类目树交互改造，尚未验收
+### 1.27 历史状态（2026-09-10）：平台级预热方案已废弃

- 最新产品要求：应用启动后为 Ozon 执行一次类目树同步并持久化到 `platform_product_categories`；商品编辑页不再出现“同步/刷新类目”按钮，打开“产品类目”时直接从数据库读取并展示树形层级。
- 当前代码已开始把类目候选扩展为 `parent_id`、`is_active` 并将前端控件改为 Cascader，但仍需完成启动同步触发、旧手动同步入口清理、树形数据与表单值的最终对接，以及真实页面回归。不要把这部分当作 M3.5 已完成。
- Ozon 采集器现在保存 BreadcrumbList/可见面包屑的名称与 URL 证据，但 `common.categories` 尚未保存可直接关联缓存节点的稳定 Ozon 类目 ID。需要在编辑上下文创建/读取时按规范化层级路径匹配缓存树，并且只在 profile 尚无用户选择时回填 `platform_product_category_id`，来源标记为 `source_capture`；用户手工选择或已保存类目不能被复采覆盖。
- 类目树同步应使用一个已验证的 Ozon 店铺凭据作为平台共享缓存来源，任务去重、失败重试和并发启动保护必须明确；不能为每个商品或每次打开编辑器重复请求 Ozon。类目缓存为空时页面应显示“缓存准备中/暂无可用类目”，而不是让用户发起同步。
- 当前中间代码的 TypeScript 检查需要先构建共享 contracts，再检查 Web/API/Worker；已验证命令为：`tsc -p packages/contracts/tsconfig.json`、随后分别执行各应用 `tsc --noEmit`。启动同步与类目自动回填尚未有集成测试。
+- 原交接要求的“Worker 启动时以指定门店预热一份平台共享类目树”已被产品决策替代：类目、属性和字典缓存按门店隔离，不能再恢复平台级共享缓存或环境变量指定的共享源。
+- 保留的原则是：浏览器、日志、operation 和 outbox 事件均不携带 API Key；编辑器只读缓存，不提供类目树手动同步入口。
+
+### 1.28 开发进度（2026-09-10）：门店类目同步与来源回填
+
+- Ozon 门店凭据验证成功后，在同一事务中创建门店类目同步 operation 与 outbox 事件；Worker 使用该门店 `Client-Id + Api-Key` 请求中文类目树，并写入 `store_product_categories`。失败只标记类目同步 operation，不会把已验证的凭据改为无效。
+- 已删除编辑器的手动类目树同步接口和客户端调用。属性 schema 与字典值仍按当前类目和关键词按需同步，使用原有 Outbox/Worker 链路。
+- Cascader 显示完整缓存树路径，但表单与草稿 API 始终保存末级类目 UUID，修复了路径数组不能直接提交到 `editor-draft` 的问题。
+- 对 Ozon 来源商品，进入或读取编辑器时会将 `common.categories` 的规范化层级路径与活动缓存节点精确匹配；仅当 profile 未保存类目时写入匹配项并标记 `source_capture`。已有手工选择或此前保存的类目永远不被复采覆盖。API 集成测试覆盖回填和保护规则。
+- 已新增 API 集成测试覆盖来源回填和保护规则；仍需在有效 Ozon 门店、真实 Ozon 样本与浏览器页面上执行最终回归。本地 Docker 基础设施未启动时，该集成测试无法实际执行。
+
+### 1.29 当前完成情况与下一步（2026-09-10）
+
+已完成：
+
+- Cascader 使用完整路径显示、末级 UUID 保存；初始回显、手动切换和服务端门店归属校验均已接入。切换目标门店会清空旧门店类目及动态属性，再加载新门店缓存。
+- 门店验证成功后在同一事务创建 `store_category_tree_sync` operation/outbox；Worker 用该门店 `Client-Id + Api-Key` 和 `ZH_HANS` 拉取树。BullMQ 任务使用 5 次指数退避重试；同步失败写 operation，不使已验证门店变为无效。
+- 编辑器旧手动类目树同步接口及客户端调用已删除；来源面包屑自动匹配只在空类目时写入 `source_capture`，不会覆盖手选或已保存选择。
+- Contracts、API、Worker、Web TypeScript 检查和 Web 生产构建已通过；`git diff --check` 已通过。
+
+未完成 / 下一步：
+
+1. 为 `store_category_tree_sync` 增加门店级去重：已有有效缓存跳过；同一门店的并发验证/重复事件只允许一次实际 Ozon 请求。
+2. 新增 Worker 集成测试，覆盖空缓存首次同步、缓存跳过、并发互斥、Ozon 失败后的指数重试和 API Key 不进入队列/日志/数据库。
+3. 启动本地 PostgreSQL 与 Redis，执行 `022_store_catalog_cache.sql`，运行 API 集成测试并检查 RLS、外键和历史 profile 兼容性。
+4. 使用真实已验证 Ozon 门店和样本，在 `http://localhost:8100` 回归：类目树回显、切换店铺、保存 UUID、来源回填、不覆盖手选类目以及属性/字典按需同步。
+
+当前阻塞：本机 PostgreSQL 与 Redis 未运行，`apps/api/test/product-editor.e2e.test.ts` 连接报 `ECONNREFUSED`，因此 API 集成测试和迁移尚未实际验证。

 ## 2. 已确认产品决策

@@ -298,10 +321,9 @@ User → Workspace → Membership / Role

 当前执行顺序：

-1. 实现 Worker 启动时一次性、幂等预热 Ozon 类目树；移除编辑器手动同步 UI；Cascader 直接读取数据库树。
-2. 在创建/读取商品编辑上下文时，用来源面包屑层级与缓存 `path` 精确匹配 Ozon 类目；仅在 profile 没有用户已选类目时回填，并标记 `source_capture`。
-3. 为启动同步、空缓存、重复启动、失败重试、树形选择和自动回填补 API/Worker 集成测试；重新执行 contracts、API、Worker、Web typecheck、Web build 与真实 8100 页面回归。
-4. 完成动态属性 schema/字典缓存、候选媒体、定价、AI 任务、首次发布和在线商品同步的剩余纵向闭环。
+1. 配置专用 Ozon 类目缓存源，在真实 Ozon 样本和 8100 页面完成类目预热、树形选择及来源回填回归。
+2. 完成候选媒体选择与按需物化，并把已选素材纳入 SKU 编辑草稿。
+3. 完成定价、AI 任务与候选结果、首次发布和在线商品同步的剩余纵向闭环。

 ### 历史计划（仅供追溯）