feat(category): 类目树、类目属性、属性字典维护系统构建完成

docs/architecture/platform-product-reference-catalog.md

@@ -1,6 +1,6 @@
 # 平台级商品参考目录的归属与维护决策
 
-> 决策日期：2026-09-18。状态：平台参考目录、系统管理员维护 API/页面及定时同步链路已经实现；商品编辑器的门店级引用尚未迁移。当前商品编辑契约仍以 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 为准。本决策取代 2026-09-10「每个门店完整保存一份类目、属性和字典」的目标设计，不抹去其实现历史。
+> 决策日期：2026-09-18。状态：平台参考目录、系统管理员维护 API/页面、同步链路、商品编辑器平台级读取及首次发布预检已实现；真正的 Ozon 发布 job 尚未开发。当前商品编辑契约以 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 为准。本决策取代 2026-09-10「每个门店完整保存一份类目、属性和字典」的目标设计，不抹去其实现历史。
 
 ## 1. 依据与边界
 
@@ -19,14 +19,14 @@ Atlas 本阶段明确采用**平台级参考数据**：同一 `platform_id` 下
 
 平台参考表以 `platform_id` 隔离 Ozon、未来的 Wildberries 等平台，只保存对应平台可复用的参考元数据；不存客户凭据、商品、价格或店铺专有数据，也不使用 `store_id` 作为目录分区键。所有门店连接和商品引用仍须满足 [`development-collaboration-contract.md`](../project/development-collaboration-contract.md) 的工作空间外键与 RLS 约束。读 API 依页头平台上下文过滤，不能跨平台混用 ID，也不能据此枚举其他店铺信息。
 
-目标交互上，切换到**同一平台**的另一个门店不应清空已选类目和属性；切换平台则必须重新选择该平台的类目并按新平台 schema 校验。新门店凭据验证只处理该门店连接，不为其复制或重新同步整套平台目录；若平台目录尚未准备好，由平台级任务补齐。当前门店级外键尚未迁移前仍维持现有切换行为。
+切换到**同一平台**的另一个门店不会清空已选类目和属性；切换平台则必须重新选择该平台的类目并按新平台 schema 校验。新门店凭据验证只处理该门店连接，不为其复制或重新同步整套平台目录；若平台目录尚未准备好，由平台级任务补齐。
 
-## 3. 同步方案：自动为主、人工为辅
+## 3. 同步方案：当前实现与已确认目标
 
 统一的后台同步服务按 `platform_id` 负责定时任务、首次缺失时的补齐和管理员手动请求。三种触发方式都创建有权限校验、幂等去重的 `platform_catalog_sync_runs + platform_catalog_outbox_events`；这是不带 `workspace_id` 的全局任务事实，不能借用租户 `operations/outbox_events`。Worker 通过平台适配器读取服务端安全存储的参考源凭据并调用对应平台。浏览器、日志、run 和 outbox 载荷不包含 API Key。管理员手动同步不得在 HTTP 请求内直接访问平台或绕过同一套限流、审计与事务发布流程。
 
 1. **同步来源**：每个平台分别配置 Atlas 专用的参考源凭据及适配器；Ozon 首期使用专用参考门店凭据作为技术采集身份，而非普通客户工作空间门店。设置最小授权、密钥轮换、失效告警与备用源，不能未经授权借用客户门店密钥。若暂无专用凭据，保持现有门店级链路，待来源配置完成后迁移。
-2. **基线调度**：当前实现为类目树和类型属性成功后 24 小时内不重复、字典成功后 7 天内不重复；调度器每 60 秒扫描，每个平台最多 6 个活动任务。BullMQ 最多尝试 5 次并从 5 秒开始指数退避。当前固定按树、属性、字典排序，在数千类型下会造成字典饥饿；后续必须改为属性/字典配额轮转，并增加近期访问优先级。具体间隔是 Atlas 运营参数，不是 Ozon 文档承诺的 TTL。
+2. **基线调度（当前代码事实）**：类目树最近成功时间达到 7 天后由调度器创建低优先级周任务；管理员仍可手动创建高优先级树任务。类型属性和字典已经退出周期自动候选，类型属性只从管理员显式创建的三种批次中逐批领取，字典只保留单项手动入口。普通商品读路径已按 14/21 天执行 fresh/stale/expired/missing 状态机，并创建或复用 user_access 平台任务。
 3. **管理员页面**：按平台展示参考源状态、树、属性、字典候选值、最后成功时间、失败详情、排队任务和「同步类目树 / 指定类目属性 / 指定字典」操作。手动动作必须受系统管理员权限控制、记录操作者，并返回异步任务；页面不展示密钥明文。当前实现位于 `/system/platform-catalog`，全局系统管理员授权独立于工作空间角色。
 4. **读路径**：正常用户只读 Atlas 缓存。首次缺失时可排队补齐并显示准备中；已有数据过期时优先提供上次成功快照并后台更新。不能在每次打开编辑器或下拉框时同步请求 Ozon。大字典搜索按规范化关键词及上述字典作用域共享缓存，并去重并发补齐。
 5. **原子性与监控**：P0 按平台及树、类型属性、字典作用域在单事务内 upsert，提交前读取方继续看到旧数据；失败保留上次成功缓存。仅在确认完整分页完成后才处理消失的字典值，部分同步记录 `is_complete=false`。当前尚未实现不可变版本快照、内容哈希、`next_refresh_at`、连续失败告警和异常删减保护，这些属于上线前可靠性加固，不能在文档中误记为已完成。
@@ -41,6 +41,6 @@ Ozon 字典分页每次最多 2000 个值；[搜索接口](https://docs.ozon.ru/
 
 ## 5. 从现有实现迁移
 
-当前 `022_store_catalog_cache.sql` 的 `store_product_categories`、属性和字典表，以及 profile 的 `store_product_category_id` 外键都是已上线的门店级事实，**本次文档决策不改变它们**。旧 `001_foundation.sql` / `021_product_category_attribute_schema.sql` 虽已有平台级表，但原字典唯一键不足以表达按类目/类型变化的字典；不能直接当成最终系统目录复用。
+`022_store_catalog_cache.sql` 的门店级表和 profile 的 `store_product_category_id` 仍保留为兼容/回滚数据，但商品编辑器不再读取它们。当前事实来源是平台级类目、属性和 `platform_catalog_dictionary_values`。
 
-迁移 `024_platform_catalog_management.sql` 已补齐以 `platform_id` 为作用域的参考来源、候选值和同步任务表，**没有建立门店差异表**；API、Worker 和管理页面已经按该作用域工作。下一步仍需以 Ozon 外部 ID 对照旧门店记录、回填平台目录。草稿/接口迁移应先提供兼容读写与可回滚映射，逐步改为平台目录引用，最后经校验和维护者批准再清理冗余门店缓存。现有商品编辑 HTTP 路径、UUID 含义和门店同步 operation 尚未改变；任何契约变更须先更新 `docs/api/`、共享类型和测试。Wildberries 等新平台应新增平台适配器及自己的外部 ID 映射，不复用 Ozon 的 `description_category_id + type_id` 语义。
+迁移 `024`～`026` 建立平台参考来源、候选值、同步任务、策略和资源状态；`027_product_editor_platform_catalog.sql` 以 Ozon 外部类目/类型 ID 回填商品的 `platform_product_category_id`，并为部分字典增加关键词搜索任务作用域。旧门店列和表暂不删除，新保存会尽量反写可映射的门店类目 UUID，供回滚使用。清理旧表必须在发布链路迁移、稳定性验证和维护者批准后另行执行。Wildberries 等新平台应新增平台适配器及自己的外部 ID 映射，不复用 Ozon 的 `description_category_id + type_id` 语义。