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

docs/api/product-editor-and-publishing.md

@@ -1,10 +1,10 @@
 # 商品编辑与首次上架 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 在门店 Ozon 凭据验证成功后同步该门店的中文类目树，编辑器只读取当前目标门店缓存；属性和字典按需同步。媒体选择、定价、AI 任务与发布仍是冻结契约，尚未实现。
+> M3.0～M3.4 已实现编辑上下文、草稿、SKU、来源素材、类目和动态属性。平台目录刷新方案第 1～4 步已把类目树、类型属性、字典读取及发布预检迁至平台级缓存：编辑器按需刷新，首次发布预检只刷新当前类型和实际使用的字典。素材选择已实现；定价确认、AI 任务、真正调用 Ozon 的首次发布 job 仍是冻结契约，尚未实现。
 
 > 此处的商品始终是采集箱内的 Atlas 草稿。所有平台范围接口要求 `X-Atlas-Platform-Id`。商品通用资料可以跨平台复用；`product_platform_profile`、SKU 首次导入状态和在线商品不能跨平台/门店复用。
 
-> 架构迁移说明：2026-09-18 已决定将类目/商品类型树、属性定义和字典候选值迁至[平台级参考目录](../architecture/platform-product-reference-catalog.md)，同一平台所有门店共用，不维护门店差异层。本文件以下字段、UUID 和同步端点仍描述**当前已实现的门店级契约**；迁移前不得把它们解释为已经共享。未来调整须先修订本契约、共享类型和测试。
+> 架构迁移说明：2026-09-18 已决定将类目/商品类型树、属性定义和字典候选值迁至[平台级参考目录](../architecture/platform-product-reference-catalog.md)，同一平台所有门店共用，不维护门店差异层。迁移已完成到商品编辑和发布预检；旧门店级目录表仅保留兼容/回滚，不再作为读取、保存或发布校验事实。
 
 ## 1. 进入编辑与读取编辑器
 
@@ -94,7 +94,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"],
-    "store_product_category_id": "uuid", "category_source": "manual" },
+    "platform_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",
@@ -112,7 +112,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.store_product_category_id` 必须是当前目标门店的活动类目；服务端从门店类目记录取得 `platform_type_id`，客户端不能伪造类型 ID。`attributes` 是完整属性草稿集合，属性 ID、复杂属性 ID、值类型、单/多值上限和字典值均由当前门店类目 schema 校验。
+- `profile.platform_product_category_id` 必须是当前平台的活动类目；同平台门店共享类目、类型属性和字典缓存。服务端从平台类目记录取得 `platform_type_id`，客户端不能伪造类型 ID。过渡期仍接受 `store_product_category_id`，但只用于按 `description_category_id + type_id` 映射平台类目，不参与当前读取和校验。
 - 类目切换或平台 schema 移除属性时，原有不再适用的属性不会进入新的发布草稿；服务端将它们写入 `unmapped_attributes` 并在编辑快照中返回。用户删除 SKU 时，其 SKU 属性随 SKU 一起移除，不生成无主未映射属性。
 - `variants` 是当前完整未删除 SKU 集合。省略既有 SKU 表示软删除；无论当前 SPU 状态都允许新增、复制、删除。`copy_from_variant_id` 仅用于新行，复制通用 SKU 数据但不复制任何平台导入映射，生成的新 SKU 从 `not_listed` 开始。
 - 删除已导入 SKU 只从 Atlas 草稿及当前平台可发布集合移除，**不删除、不下架、不修改** Ozon 商品或在线镜像；其他平台历史映射保留。删除后当前平台只剩已导入 SKU 时，SPU 汇总自然为“已上架”。
@@ -132,23 +132,25 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": "
 
 `GET /api/product-platform-profiles/{profile_id}/attribute-schema`
 
-当前 profile 必须已有类目。返回本地同步的字段 schema：`platform_attribute_id`、`complex_id`、名称、`value_type`、`is_required`、`is_collection`、`max_value_count`、`dictionary_id`、`is_aspect` 与 `editor_field`。`editor_field` 只按 Ozon 属性 ID 计算，不允许按名称或翻译文本匹配：品牌 `85 → brand`、型号名称 `9048 → model`、类型 `8229 → category`、主题标签 `23171 → tags`、JSON 富内容 `11254 → rich_content`、简介/产品描述 `4191 → description`，其他 ID 返回 `null`。非空字段由编辑器已有控件承载，动态属性区不得重复展示或加载字典；服务端会兼容但忽略旧客户端重复提交的映射属性。可带 `?category_id={uuid}` 预览尚未保存的新类目 schema；该类目仍必须属于当前平台且为活动状态。类别未选返回 `422 CATEGORY_REQUIRED`。
+当前 profile 必须已有平台类目。响应包含 `{ items, cache }`；字段 schema 额外返回 Atlas `attribute_id`，供字典接口精确限定属性作用域，其余字段包括 `platform_attribute_id`、`complex_id`、名称、`value_type`、`is_required`、`is_collection`、`max_value_count`、`dictionary_id`、`is_aspect` 与 `editor_field`。`editor_field` 只按 Ozon 属性 ID 计算，不允许按名称或翻译文本匹配：品牌 `85 → brand`、型号名称 `9048 → model`、类型 `8229 → category`、主题标签 `23171 → tags`、JSON 富内容 `11254 → rich_content`、简介/产品描述 `4191 → description`，其他 ID 返回 `null`。可带 `?category_id={platform_category_uuid}` 预览尚未保存的新类目 schema。
 
-`GET /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{dictionary_id}?q={keyword}&cursor={opaque}`
+`cache.status` 为 `fresh | stale | expired | missing`，并返回 `last_success_at`、`fresh_until`、`expires_at`、`is_complete`、`refresh_run_id`、`refresh_status` 和 `retry_after_ms`。fresh 直接返回；stale 返回旧 schema 并创建或复用低优先级平台任务；expired/missing 创建或复用高优先级平台任务并最多等待 5 秒，仍未完成时以 HTTP `202` 返回空 `items` 和缓存状态。API 不直连 Ozon。
 
-返回本地同步的字典值 `{ items: [{ value_id, value }], next_cursor }`，每页最多 200 项；传入 `next_cursor` 可继续读取，`null` 表示本地缓存已读完。可同样传 `category_id` 读取尚未保存的新类目。字典必须属于当前类目 schema，否则返回 `422 ATTRIBUTE_DICTIONARY_INVALID`；无效游标返回 `400 VALIDATION_FAILED`。接口只读取缓存，不让前端直接持有 Ozon 密钥或直接调用 Ozon。
+`GET /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{attribute_id}?q={keyword}&cursor={opaque}`
+
+返回 `{ items: [{ value_id, value }], next_cursor, cache }`，每页最多 200 项。`attribute_id` 是 schema 返回的 Atlas 平台属性 UUID，不再只用可能跨类型重复的 Ozon `dictionary_id` 定位。完整字典使用字典整体状态；部分字典本地搜索未命中时，规范化关键词使用独立 `dictionary_search` 状态。fresh/stale/expired/missing 的返回、优先级和 5 秒等待规则与 schema 相同；expired/missing 的旧候选值不作为当前选项返回。
 
 `GET /api/product-platform-profiles/{profile_id}/category-options?q={keyword}`
 
-返回当前目标门店的缓存类目树节点，包含本地 UUID、父节点 UUID、平台外部类目/类型 ID、名称、路径和活动状态。选择类目本身不立即写库，随下一次 `editor-draft` 原子保存。缓存为空时客户端显示“准备中”，编辑器不提供同步按钮；当前 Worker 在门店凭据验证成功后用该门店凭据同步树。平台级共享参考源属于待迁移目标，不是本接口的现有行为。
+返回当前平台共享的缓存类目树节点，包含平台类目 UUID、父节点 UUID、Ozon `description_category_id` / `type_id`、名称、路径和活动状态。接口不再接收或使用 `store_id`；切换同平台目标门店不会清空类目。树为空时客户端提示联系系统管理员同步。
 
 `POST /api/product-platform-profiles/{profile_id}/attribute-schema-syncs?category_id={uuid}`
 
-为已选门店活动类目创建 `store_category_attribute_sync` operation。同步以单类目事务替换该门店 schema；下一次编辑草稿保存会依最新 schema 校验并将不匹配旧值转为未映射草稿。
+兼容入口：为平台类目创建或复用高优先级 `platform_catalog_sync_runs`。普通编辑器读取已自动按新鲜度触发刷新，不要求用户先点击本接口。
 
-`POST /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{dictionary_id}/syncs?category_id={uuid}&q={keyword}`
+`POST /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{attribute_id}/syncs?category_id={uuid}&q={keyword}`
 
-不传 `q` 时创建 `store_attribute_dictionary_sync` operation，Worker 从该门店的 Ozon 字典值接口按游标读取首批最多 1000 项并 upsert 本地缓存；打开字典控件时可按需触发，当前类目下同一字典只自动触发一次，切换类目后重新评估，不在加载类目时同时同步全部字典。传入 `q` 时至少两个字符，Worker 使用 Ozon 字典搜索接口 upsert 命中的值；前端输入关键词后延迟触发，以便从超过首批范围的大字典中继续查找。所有字典属性均由 schema 的 `dictionary_id` 驱动，不根据中文属性名维护固定选项。Ozon 密钥始终留在 Worker。
+兼容入口：不传 `q` 时刷新该平台属性的字典批次；传入至少两个字符的 `q` 时刷新独立关键词作用域。任务写入平台 Outbox，由 Worker 使用系统后台配置的平台参考源凭据调用 Ozon，响应不会携带密钥。
 
 `GET /api/product-platform-profiles/{profile_id}/validation`
 
@@ -191,6 +193,23 @@ Headers：`If-Match`、`Idempotency-Key` 必填。Body：`{ "target_store_id": "
 
 `profile.issues` 包含商品级基础信息、类目 schema 和 `is_aspect=false` 的必填属性；每个 SKU 的 `issues` 包含货号、价格、有效包装规格、图片和 `is_aspect=true` 的必填属性。只有 `confirmation_status=confirmed` 且包含非空值的属性满足发布要求。`ready=true` 要求 profile 无问题、至少存在一个未上架 SKU，且全部未上架 SKU 均通过校验。
 
+`POST /api/product-platform-profiles/{profile_id}/publish-preflights`
+
+Body：`{ "variant_ids": ["uuid", "uuid"] }`，最多 100 个且不能重复。该接口是创建真正发布 job 之前的可重算预检，不固化商品发布快照；平台目录任务按资源 `scope_key` 幂等合并，因此重复预检不会并发重复请求 Ozon。
+
+预检只接受当前 profile 下 `not_listed` / `failed` 的未删除 SKU。`submitting` 返回 `409 SKU_IMPORT_IN_PROGRESS`，`imported` 返回 `422 SKU_ALREADY_IMPORTED`，不属于当前商品或已删除返回 `422 PUBLISH_VARIANTS_INVALID`。
+
+目录处理顺序：
+
+1. 只检查当前 `platform_product_category_id` 的 schema。fresh 直接使用；stale 使用旧 schema 并创建/复用 low、`trigger_kind=publish` 的平台任务；expired/missing 创建/复用 high 任务。
+2. schema 可用后，从本次 SKU 集合的已确认草稿中提取实际使用的字典属性。未填写的可选字典、其他 SKU 和同类型下未使用字典都不刷新。
+3. 字典沿用相同 14/21 天状态机。expired/missing 候选值不能作为发布依据；预检最多共用一个 5 秒等待窗口观察所有 high Worker 任务，不按字典数量逐项累加等待。
+4. high schema 成功后，预检再根据新 schema 计算字典依赖；最后重新执行必填、scope、包装、价格、图片以及字典值有效性校验。
+
+可立即完成时返回 HTTP `200`；仍在等待 high 任务时返回 HTTP `202`。响应包含 `status=ready|blocked|refreshing`、完整 `validation`、schema/已用字典的 `catalog` cache 元数据，以及本次创建或复用的 `refresh_runs`。
+
+`refreshing` 时客户端使用相同 SKU 集合重新预检；不得退回过期缓存。`blocked` 表示目录资源可用但商品草稿仍有业务校验问题；`ready` 才能进入未来的发布快照创建事务。Ozon 最终仍可能拒绝 payload，该错误属于具体商品/门店的发布结果，不能据此创建门店级目录副本。
+
 ## 4. SKU 定价确认
 
 `POST /api/product-platform-profiles/{profile_id}/variants/{variant_id}/pricing-confirms`
@@ -244,6 +263,8 @@ Headers：`If-Match`、`Idempotency-Key` 必填。用户确认后才将候选写
 
 ## 7. 部分 SKU 首次上架
 
+> 当前实现到上述 `publish-preflights`。以下 `publish-jobs`、Ozon `/v3/product/import` 提交和结果轮询仍是冻结契约，尚未开发；不得把预检 `ready` 当成已经提交或发布成功。
+
 `POST /api/product-platform-profiles/{profile_id}/publish-jobs`
 
 Headers：`Idempotency-Key` 必填。Body：