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

docs/project/HANDOFF.md

@@ -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 任务与候选结果、首次发布和在线商品同步的剩余纵向闭环。
 
 ### 历史计划（仅供追溯）