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

docs/api/README.md

@@ -16,9 +16,9 @@ API 启动后会在 `/api-docs` 提供 Swagger UI，并在其 OpenAPI 文档中
 | [`watermarks-and-assets.md`](./watermarks-and-assets.md) | 部分已实现 | 水印模板、字体、店铺推荐水印，以及水印图片直传、校验和短时预览；图片渲染派生待实现。 |
 | [`pricing.md`](./pricing.md) | 已设计 | 汇率、物流价卡、即时试算、定价方案、报价快照衔接。 |
 | [`collection-and-extension.md`](./collection-and-extension.md) | 已设计 | 插件授权、采集写入、采集箱查询、素材转存与状态。 |
-| [`product-editor-and-publishing.md`](./product-editor-and-publishing.md) | M3.5 部分已实现 | 编辑上下文、完整 SKU 草稿、店铺切换、规格继承、AI 来源素材字段级合并，以及 Ozon 类目树、动态属性和关键词字典缓存同步；媒体、定价、AI 任务与首次上架仍待实现。 |
+| [`product-editor-and-publishing.md`](./product-editor-and-publishing.md) | 编辑器与发布预检已实现 | 编辑上下文、完整 SKU 草稿、店铺切换、规格继承、AI 来源素材字段级合并、平台级 Ozon 类目/属性/字典按需刷新及首次上架目录预检；定价、AI 任务与真正的 Ozon 发布 job 仍待实现。 |
 | [`online-listings.md`](./online-listings.md) | 初版已设计 | 店铺独有的在线商品镜像、读取与异步同步；编辑/认领仍待讨论。 |
-| [`platform-catalog-admin.md`](./platform-catalog-admin.md) | 已实现 | 全局系统管理员授权、平台参考源配置、类目/属性/字典读取、手动同步和任务状态。 |
+| [`platform-catalog-admin.md`](./platform-catalog-admin.md) | 已实现 | 全局系统管理员授权、平台参考源配置、类目/属性/字典读取、每周树同步、刷新策略、三种类型属性批次、优先级、任务状态及后台页面。 |
 
 旧的 [`../product/api.md`](../product/api.md) 是商品域的早期草案：已确认的产品规则可作为背景，但不能当作最终 HTTP 契约。后续商品模块会迁入本目录并替换其中的路径和细节。
 

docs/api/platform-catalog-admin.md

@@ -1,6 +1,6 @@
 # 平台类目与属性管理 API
 
-> 2026-09-18 新增契约。平台级目录供系统管理员维护；普通商品编辑器现有门店级 API 暂不改变。平台参考目录的归属见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)。
+> 2026-09-18 新增契约，2026-09-20 增加平台刷新策略和类型属性批次。平台级目录供系统管理员维护；普通商品编辑器现有门店级 API 暂不改变。平台参考目录的归属见 [`platform-product-reference-catalog.md`](../architecture/platform-product-reference-catalog.md)，新鲜度与优先级规则见 [`platform-catalog-cache-refresh-plan.md`](../architecture/platform-catalog-cache-refresh-plan.md)。
 
 ## 权限与安全
 
@@ -29,7 +29,7 @@ ON CONFLICT (user_id) DO UPDATE SET revoked_at = NULL, granted_at = now();
 
 `GET /api/system/platform-catalog/platforms`
 
-返回 `{ "data": [{ "id", "code", "name", "source": { "configured", "client_id_hint", "updated_at" }, "summary": { "category_count", "last_tree_sync_at", "last_error" } }] }`。`client_id_hint` 仅为脱敏末尾字符，不返回 API Key、密文或指纹。
+返回 `{ "data": [{ "id", "code", "name", "source": { "configured", "client_id_hint", "updated_at" }, "summary": { "category_count", "last_tree_sync_at", "next_tree_sync_at", "last_error" } }] }`。`client_id_hint` 仅为脱敏末尾字符，不返回 API Key、密文或指纹。`next_tree_sync_at` 固定为最近成功时间后 7 天；从未成功时为 `null` 并由调度器尽快创建首次任务。
 
 `PUT /api/system/platform-catalog/platforms/{platform_id}/source`
 
@@ -37,11 +37,33 @@ Body：`{ "client_id": "...", "api_key": "..." }`。仅 Ozon 适配器接受当
 
 `GET /api/system/platform-catalog/platforms/{platform_id}/categories`
 
-返回当前平台的全部树节点 `{ id, parent_id, external_category_id, external_type_id, name, path, is_active, synced_at }`；按父子关系在客户端构建树，目录节点可展开，仅可发布类型叶子用于查看属性。
+返回当前平台的全部树节点 `{ id, parent_id, external_category_id, external_type_id, name, path, is_active, synced_at, attribute_last_success_at, attribute_cache_status, attribute_last_error, attribute_last_error_at }`；按父子关系在客户端构建树，目录节点可展开，仅可发布类型叶子用于查看属性。纯目录节点的属性状态为 `null`；可发布类型状态为 `fresh | stale | expired | missing`。
+
+`GET /api/system/platform-catalog/platforms/{platform_id}/refresh-policy`
+
+返回平台目录刷新策略：
+
+```json
+{
+  "data": {
+    "attribute_fresh_days": 14,
+    "attribute_expire_days": 21,
+    "dictionary_fresh_days": 14,
+    "dictionary_expire_days": 21,
+    "updated_at": "2026-09-20T00:00:00Z"
+  }
+}
+```
+
+尚未显式配置的平台返回相同默认值。类目树固定每 7 天同步，不属于可配置策略。
+
+`PUT /api/system/platform-catalog/platforms/{platform_id}/refresh-policy`
+
+Body 必须完整提交 `{ "attribute_fresh_days", "attribute_expire_days", "dictionary_fresh_days", "dictionary_expire_days" }`。四项均为 `1..365` 的整数，同类资源的 `expire_days` 必须严格大于 `fresh_days`。成功保存后立即影响后续状态判断，但不得因此主动扫描或创建属性/字典任务；服务端记录修改人和时间。
 
 `GET /api/system/platform-catalog/platforms/{platform_id}/categories/{category_id}/attributes`
 
-返回该类型的属性定义 `{ id, platform_attribute_id, complex_id, name, description, group_name, value_type, is_required, is_aspect, is_collection, max_value_count, dictionary_id, is_active, synced_at, dictionary_value_count }`。`category_id` 不属于所选平台时返回 404。
+返回该类型的属性定义 `{ id, platform_attribute_id, complex_id, name, description, group_name, value_type, is_required, is_aspect, is_collection, max_value_count, dictionary_id, is_active, synced_at, last_success_at, cache_status, last_error_message, last_error_at, dictionary_last_success_at, dictionary_cache_status, dictionary_is_complete, dictionary_last_error_message, dictionary_last_error_at, dictionary_value_count }`。类型级 `last_success_at/cache_status` 会在该类型的每个属性行重复，便于管理页展示；没有任何属性行时应结合属性汇总或资源状态判断 missing。`category_id` 不属于所选平台时返回 404。
 
 `GET /api/system/platform-catalog/platforms/{platform_id}/attributes/{attribute_id}/values?q={keyword}&page={number}`
 
@@ -49,8 +71,52 @@ Body：`{ "client_id": "...", "api_key": "..." }`。仅 Ozon 适配器接受当
 
 `POST /api/system/platform-catalog/platforms/{platform_id}/syncs`
 
-Headers：`Idempotency-Key`（UUID）必填。Body：`{ "scope": "tree" | "attributes" | "dictionary", "category_id"?: "uuid", "attribute_id"?: "uuid" }`。树同步不带其他 ID；属性同步需要当前平台的可发布 `category_id`；字典同步需要该类型下带字典的 `attribute_id`。同作用域已有 queued/running 任务时返回已有任务，并将本次幂等键持久映射到该任务；同一用户重试不会在原任务完成后意外创建第二个任务。成功排队返回 `202` 与 `{ "data": { "id", "platform_id", "scope", "status", "trigger", "created_at" } }`。同步由 Worker 异步执行，失败保留上次成功缓存。
+Headers：`Idempotency-Key`（UUID）必填。Body：`{ "scope": "tree" | "attributes" | "dictionary", "category_id"?: "uuid", "attribute_id"?: "uuid" }`。树同步不带其他 ID；兼容的单类型属性同步需要当前平台的可发布 `category_id`；字典同步需要该类型下带字典的 `attribute_id`。同作用域已有 queued/running 任务时返回已有任务，并将本次幂等键持久映射到该任务；同一用户重试不会在原任务完成后意外创建第二个任务。成功排队返回 `202` 与 `{ "data": { "id", "platform_id", "scope", "status", "trigger", "priority", "created_at" } }`。同步由 Worker 异步执行，失败保留上次成功缓存。树任务优先级独立决定；属性和字典根据资源年龄选择 `low` 或 `high`，missing/严格超过过期阈值为 `high`。
+
+`GET /api/system/platform-catalog/platforms/{platform_id}/attribute-sync-summary`
+
+返回当前策略下活动可发布类型的聚合数量：
+
+```json
+{
+  "data": {
+    "total": 7365,
+    "fresh": 100,
+    "stale": 200,
+    "expired": 300,
+    "missing": 6765,
+    "active_batch_id": null,
+    "evaluated_at": "2026-09-20T00:00:00Z"
+  }
+}
+```
+
+状态边界严格按平台策略和最近成功时间计算：`age < fresh_days` 为 fresh，`fresh_days ≤ age ≤ expire_days` 为 stale，`age > expire_days` 为 expired，从未成功为 missing。
+
+`POST /api/system/platform-catalog/platforms/{platform_id}/attribute-sync-batches`
+
+Headers：`Idempotency-Key`（UUID）必填。Body：
+
+```json
+{ "mode": "missing_expired" | "missing_stale_expired" | "all" }
+```
+
+- `missing_expired` 固定 missing、expired 类型快照；
+- `missing_stale_expired` 固定 missing、stale、expired 类型快照；
+- `all` 固定全部活动可发布类型快照，包含 fresh。
+
+没有命中类型时返回 `422 CATALOG_ATTRIBUTE_BATCH_EMPTY`。同一平台已有 queued/running 批次时返回 `409 CATALOG_ATTRIBUTE_BATCH_ACTIVE` 和现有批次 ID，避免两个全量扫描互相竞争。成功返回 `202` 与批次 `{ id, platform_id, mode, status, total_count, pending_count, running_count, succeeded_count, failed_count, cancelled_count, created_at, started_at, completed_at }`。Worker 每分钟限量领取批次项；missing/expired 子任务为高优先级，fresh/stale 子任务为低优先级。批次创建后新增的类型不加入本批次。
+
+`GET /api/system/platform-catalog/platforms/{platform_id}/attribute-sync-batches?limit={number}`
+
+返回最近批次及实时聚合进度，最多 50 条。批次允许部分失败：任一子任务失败时最终状态为 `failed`，但成功类型继续保留且不会回滚。
+
+`GET /api/system/platform-catalog/platforms/{platform_id}/attribute-sync-batches/{batch_id}`
+
+返回单个批次的相同进度字段；批次不属于当前平台时返回 404。
 
 `GET /api/system/platform-catalog/platforms/{platform_id}/syncs?limit={number}`
 
 返回该平台最近的同步任务（最多 50 条），包括作用域、触发方式、状态、开始/完成时间、数量摘要及脱敏错误。系统管理员可据此查看手动和定时更新结果。
+
+类目树调度固定为最近一次成功后 7 天。类型属性和属性字典没有周期性自动扫描；它们只由管理员操作、后续普通用户访问和发布前校验创建任务。

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：

docs/architecture/platform-catalog-cache-refresh-plan.md

@@ -0,0 +1,263 @@
+# 平台目录缓存、新鲜度与按需刷新方案
+
+> 方案日期：2026-09-20。状态：**第 1～4 步已实现**。  
+> 迁移 `025`～`027`、系统管理 API/页面、Worker 调度、商品编辑器平台级读取及首次发布预检均已落地。真正的 Ozon 首次发布 job 尚未开发；“第 4 步完成”仅指发布前目录刷新与最终本地校验已具备稳定复用入口。
+
+## 1. 目标与非目标
+
+本方案解决三个问题：
+
+1. 类目树、类型属性和属性字典只保存一份平台级参考数据，同平台所有门店和用户共同使用。
+2. 类目树通过低频自动同步维持基线；类型属性和属性字典不做周期性全量自动同步，改为管理员发起、用户访问触发和发布前校验。
+3. 用户读取缓存时按新鲜度决定直接返回、后台刷新或等待高优先级刷新；Ozon 请求始终由 Worker 执行，不在 API 进程同步直连。
+
+本阶段不实现门店差异层，不依赖 Ozon 聊天通知，也不假设 Ozon 提供类目变更 Feed。商品/SKU 已填值、门店凭据、发布结果和错误仍属于工作空间业务数据，不迁入平台参考目录。
+
+## 2. 平台级唯一归属
+
+| 参考数据 | 归属与读取键 | 禁止行为 |
+|---|---|---|
+| 类目/商品类型树 | `platform_id + external_category_id + external_type_id` | 不按 `store_id` 复制，不用名称匹配，不因切换同平台门店重新同步 |
+| 类型属性定义 | `platform_id + platform_product_category_id + platform_attribute_id + complex_id` | 不保存门店级属性定义，不使用门店凭据刷新普通商品编辑缓存 |
+| 属性字典候选值 | `platform_id + platform_product_category_id + attribute_id + external_value_id` | 不只按 `dictionary_id` 跨类型合并，不按门店保存同一候选值副本 |
+
+所有普通读路径、发布校验和系统后台都读取平台级表。商品编辑器迁移时以 Ozon `description_category_id + type_id` 将现有门店类目引用映射到平台类目 UUID，再把属性和字典读取切换到平台级；迁移完成前保留旧表用于兼容和回滚，不能混用新旧 UUID。
+
+平台目录只使用系统后台为该平台配置的专用参考源凭据。普通用户不会选择同步门店，API 响应和任务载荷不包含 `Api-Key`；只有 Worker 在调用平台时短暂解密凭据。
+
+## 3. 同步触发规则
+
+### 3.1 类目树
+
+- 每个平台每 7 天自动同步一次完整类目/商品类型树。
+- 周期从最近一次成功完成时间计算；失败不更新成功时间，按 Worker 重试策略处理。
+- 系统后台保留“同步类目树”按钮。管理员手动同步绕过 7 天周期，但复用相同平台上已有的 queued/running 树任务，不重复调用 Ozon。
+- 首次配置或更换平台参考源凭据时，自动创建一次树同步任务。
+- 树同步完成后只更新节点、父子关系、活动状态和树级同步状态，不自动展开为全部类型属性或字典任务。
+
+类目树自动同步是唯一固定周期同步。类型属性和属性字典均不再由定时器按 TTL 扫描并自动创建任务。
+
+### 3.2 类型属性
+
+类型属性有三种触发来源：
+
+1. 普通用户读取商品编辑数据时发现缓存为 stale、expired 或 missing。
+2. 发布任务在校验当前商品类型时发现缓存为 expired 或 missing。
+3. 系统管理员在后台按所需范围启动一次类型属性同步批次。
+
+系统管理员不需要逐个类型点击同步。后台提供三个批次入口：
+
+| 按钮 | 批次快照包含范围 | 不包含范围 |
+|---|---|---|
+| 同步未缓存和过期类型属性 | `missing`、`expired`（`age > 过期阈值`） | `fresh`、`stale` |
+| 同步未缓存和不新鲜类型属性 | `missing`、`stale`、`expired`（`age ≥ 新鲜阈值`，以及从未成功同步） | `fresh` |
+| 同步全部类型属性 | 全部活动且可发布类型，不考虑缓存年龄 | 无 |
+
+“同步全部类型属性”必须使用红色危险按钮；点击后弹出二次确认，明确展示将处理的类型数量、任务为低速后台批次且可能持续较长时间。用户确认前不得创建批次或子任务。前两个按钮使用普通按钮，但仍需在创建前展示本次命中的类型数量；命中数量为 0 时禁用操作并提示无需同步。
+
+任一批次启动后：
+
+- 固定一份当时活动且可发布的类型快照；后续树同步新增的类型不悄悄加入已经开始的批次。
+- 创建父批次记录，记录总数、等待数、运行数、成功数、失败数和取消数。
+- Worker/调度器按限流能力逐步生成或领取类型子任务，不把数千任务一次性全部压入 Redis。
+- 已有相同 `scope_key` 的 queued/running 任务时直接复用，并计入批次结果。
+- 批次只处理对应按钮命中的快照范围；“同步全部类型属性”会请求 fresh 类型。每个子任务的优先级仍按第 5 节的资源年龄计算，管理员批次本身不把 fresh/stale 任务提升为高优先级。
+- 批次失败不回滚其他已成功类型，也不清空任何旧缓存。
+
+### 3.3 属性字典
+
+- 不做周期性全平台或全属性自动同步。
+- 系统后台保留选择某个类型属性后“同步此字典”的单项操作。
+- 普通用户打开字典控件或搜索候选值时，先读取 Atlas 平台缓存，再按第 4 节状态决定是否创建刷新任务。
+- 类型属性刷新发现新增字典、`dictionary_id` 变化或属性作用域变化时，只把受影响字典标记为 missing/stale，不自动同步该类型的全部字典。
+- 相同平台、类型、属性和规范化搜索词的并发补齐请求必须合并，不因用户或门店不同重复请求 Ozon。
+
+字典的完整性与新鲜度是两个独立维度：
+
+- `is_complete=true` 表示最近一次完整分页已经结束，可以据此处理 Ozon 已删除的旧值。
+- `is_complete=false` 表示当前只有部分候选值；已有值仍可按新鲜度使用，但本地搜索未命中不能证明 Ozon 没有该值。
+- 部分字典的“查询词补齐”作为独立缓存作用域记录成功时间；该查询词从未请求成功时视为 missing，按高优先级处理。搜索命中不会把整个字典改成完整。
+
+## 4. 新鲜度状态机
+
+类型属性和属性字典默认都使用：
+
+- 新鲜时间：14 天；
+- 过期时间：21 天。
+
+资源年龄使用 `now - last_success_at` 计算，`last_success_at` 只在 Ozon 请求成功且新缓存事务提交后更新。排队、运行、失败和取消都不能延长新鲜期。全部比较使用 UTC 实时时长，不按自然日零点取整。
+
+| 状态 | 精确条件 | Atlas 数据能否使用 | Ozon 任务 | 用户读取行为 |
+|---|---|---|---|---|
+| `fresh` | `age < 14 天` | 可以 | 不创建 | 立即返回 Atlas 缓存 |
+| `stale` | `14 天 ≤ age ≤ 21 天` | 可以 | 创建/复用低优先级任务 | 立即返回旧缓存，并标记后台刷新中 |
+| `expired` | `age > 21 天` | 不作为当前有效 schema/候选值使用 | 创建/复用高优先级任务 | 等待 Worker；成功后返回新缓存 |
+| `missing` | 从未成功同步，或当前作用域无可用快照 | 不可以 | 创建/复用高优先级任务 | 与 expired 相同 |
+
+边界规则：恰好 14 天进入 stale；恰好 21 天仍是 stale 和低优先级；超过 21 天才进入 expired 和高优先级。
+
+失败处理：
+
+- fresh/stale 的后台刷新失败时保留旧快照；在 21 天内仍可继续使用，并把失败状态提供给管理后台观察。
+- expired/missing 刷新失败时不能把旧数据伪装为有效结果。API 返回可重试错误和任务状态；已有商品草稿值必须保留，但相关控件和发布校验等待有效 schema/字典后继续。
+- 更新必须按资源作用域在单个事务中发布。读取方只能看到上一次完整成功快照或本次完整提交后的新快照，不能看到写入一半的数据。
+
+## 5. Worker 优先级、等待和任务合并
+
+Ozon 调用仍统一通过 Transactional Outbox 和 Worker：
+
+| 资源状态 | Worker 优先级 | 是否允许返回旧缓存 | API 等待策略 |
+|---|---|---|---|
+| fresh | 不创建任务 | 是 | 不等待 |
+| stale（≤21 天） | 低 | 是 | 不等待，立即返回缓存 |
+| expired（>21 天） | 高 | 否 | 最多等待短窗口，未完成则返回操作状态 |
+| missing | 高 | 否 | 与 expired 相同 |
+
+“等待 Ozon 数据”不代表 API 自己调用 Ozon。推荐交互：
+
+1. API 在事务内创建或复用平台级同步 run 和 outbox。
+2. 高优先级目录队列优先于管理员全量批次和 stale 刷新任务。
+3. API/前端可等待最多 5 秒；Worker 在窗口内成功时立即重新读取并返回新缓存。
+4. 5 秒内未完成时返回 `202`、`operation_id` 和 `cache_status=expired|missing`，前端保持加载状态并轮询或等待推送，不能退回门店缓存。
+5. stale 请求立即返回 `200` 和旧缓存，可同时返回 `refresh_operation_id`，前端无需阻塞。
+
+每个平台和资源 `scope_key` 同时最多有一个活动任务。低优先级任务已经 queued、随后资源超过 21 天时，将原任务提升为高优先级并复用同一个 run；若任务已经 running，则不启动重复任务，调用方等待同一个任务。高优先级任务只能插队尚未运行的低优先级任务，不能中断正在执行的 Ozon 请求。
+
+目录交互任务应使用独立的 Worker 并发/限流通道，避免和素材处理等任务争用；高、低优先级共享同一平台级 Ozon 限流器、429 退避、最多尝试次数和审计记录。优先级不能绕过平台限流。
+
+## 6. 普通用户读取流程
+
+普通用户不直接操作系统管理 API。产品 API 根据当前平台和平台类目 UUID读取共享目录，并返回缓存元数据。
+
+### 6.1 类型属性
+
+```text
+请求当前商品类型属性
+        ↓
+读取平台级属性快照与 last_success_at
+        ↓
+fresh ───────────────→ 200 最新 Atlas 缓存
+stale ──→ 低优先级刷新 → 200 旧缓存 + refreshing
+expired/missing ─────→ 高优先级刷新 → 短暂等待
+                                      ├─ 成功：200 新缓存
+                                      └─ 未完成：202 operation
+```
+
+类型属性刷新只调用当前 `description_category_id + type_id` 的属性接口，不刷新类目树、其他类型或全部字典。刷新后比较属性 ID、复杂属性 ID、必填、SKU 维度、类型、数量、字典 ID 和依赖信息，并只失效受影响的字典缓存。
+
+### 6.2 属性字典
+
+1. 打开下拉框时先读取平台级字典缓存。
+2. fresh 时立即返回；complete 字典的本地未命中直接视为无结果。
+3. stale 时立即返回旧候选值并创建低优先级刷新任务。
+4. expired/missing 时创建高优先级任务，更新 Atlas 后才能作为当前候选值返回。
+5. partial 字典本地搜索未命中时，检查规范化查询词缓存；查询词 missing/expired 时创建高优先级搜索任务，成功结果先写入平台缓存再返回。
+6. 前端可以先显示 stale/partial 的已有候选值，但不能把“部分缓存未命中”展示成 Ozon 确认不存在。
+
+浏览器永远不接收 Ozon 原始凭据，也不使用 Ozon 响应作为未落库的临时事实。任何返回给用户的新候选值都必须已经成功写入 Atlas 平台缓存。
+
+## 7. 发布前校验
+
+- 发布任务只检查商品当前引用的类型属性，不扫描其他类型。
+- fresh/stale 类型属性可以用于发布校验；stale 同时创建低优先级刷新，但不阻止本次发布进入后续校验。
+- expired/missing 类型属性必须先通过高优先级 Worker 刷新，再使用新 schema 校验必填项、scope 和数量限制。
+- 发布使用到的字典值必须存在于该平台、类型和属性作用域的有效缓存。相关字典 expired/missing 时先刷新对应字典或目标查询作用域，不刷新该类型下所有字典。
+- Ozon 最终仍可能返回平台校验错误；这类错误按商品/门店记录，必要时将对应平台参考资源标记为需要重新检查，但不能自动生成门店差异层。
+
+## 8. 系统后台调整
+
+「平台类目与属性」页面保留现有平台选择、同步来源、类目树、属性和字典浏览能力，并调整为：
+
+### 8.1 操作区
+
+- “同步类目树”：立即创建/复用平台树任务。
+- “同步未缓存和过期类型属性”：只为 missing、expired 类型创建批次。
+- “同步未缓存和不新鲜类型属性”：只为 missing、stale、expired 类型创建批次。
+- “同步全部类型属性”：红色危险按钮，为所有活动可发布类型创建批次；二次确认中显示命中数量和预计耗时，确认后才能创建任务。
+- 类型详情可继续显示单类型最近成功时间和状态；本方案不要求管理员逐个点击才能完成全量属性同步。
+- 字典 Drawer 保留“同步此字典”，不增加全平台字典批次。
+
+### 8.2 新鲜度设置
+
+按平台配置以下四个整数天数：
+
+- 类型属性新鲜天数，默认 14；
+- 类型属性过期天数，默认 21；
+- 属性字典新鲜天数，默认 14；
+- 属性字典过期天数，默认 21。
+
+约束：取值建议为 `1..365`，且同一资源的过期天数必须大于新鲜天数。类目树的每周周期首期固定为 7 天，不放入该配置区。
+
+设置保存后立即用于后续读取判断，但不主动扫描并创建数千任务。例如把过期天数从 30 改为 21 后，只有下次用户读取、发布校验或管理员批次触达该资源时才创建任务。修改必须记录操作者、修改时间和前后值。
+
+### 8.3 状态展示
+
+管理页至少展示：
+
+- 类目树最近成功时间和下次计划时间；
+- 类型属性批次的总数、等待、运行、成功、失败和完成百分比；
+- 当前类型属性的 `fresh/stale/expired/missing`、最近成功时间和最近错误；
+- 字典的相同新鲜度状态、完整/部分状态、候选值数量和最近错误；
+- 高低优先级、触发来源（weekly/manual/admin_batch/user_access/publish）和任务复用关系。
+
+## 9. 建议的数据与契约调整
+
+确认后至少需要补充以下模型，具体 DDL 和字段名在实现阶段冻结：
+
+1. 平台同步策略：保存属性、字典的新鲜和过期天数以及审计字段。
+2. 资源同步状态：按 tree、类型属性、属性字典和字典搜索作用域保存 `last_success_at`、`is_complete`、最新任务及错误；不能仅依赖数据行的 `updated_at` 推断是否成功检查过。
+3. 属性批次：保存管理员批次快照和聚合进度，子任务继续使用既有平台 run/outbox 事实。
+4. 任务优先级与触发来源：区分 high/low 及 weekly、manual、admin_batch、user_access、publish。
+5. 商品编辑引用：从门店类目 UUID 迁移为平台类目 UUID；属性和值仍按当前商品/SKU 草稿保存，但校验引用平台 schema。
+
+普通产品读取响应建议统一带：
+
+```json
+{
+  "data": [],
+  "cache": {
+    "status": "fresh",
+    "last_success_at": "2026-09-20T00:00:00Z",
+    "fresh_until": "2026-10-04T00:00:00Z",
+    "expires_at": "2026-10-11T00:00:00Z",
+    "is_complete": true,
+    "refresh_run_id": null,
+    "refresh_status": null,
+    "retry_after_ms": null
+  }
+}
+```
+
+管理 API 需要增加同步策略读取/修改和类型属性批次创建/读取；现有单项 `POST .../syncs` 保留给树和字典。最终端点、状态码和错误码必须在实现前更新 [`platform-catalog-admin.md`](../api/platform-catalog-admin.md) 与 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md)。
+
+## 10. 实施顺序与验收
+
+建议分四步实施，避免继续扩大门店级缓存：
+
+1. **平台状态与调度**：增加策略、资源状态、批次和优先级；把树改为每周自动同步，关闭属性/字典周期自动扫描。
+2. **后台能力**：加入新鲜度设置、三种范围的类型属性批次入口及统一批次进度，保留树及单字典手动同步。
+3. **商品编辑迁移**：通过 Ozon 外部 ID 回填平台类目引用，切换属性和字典读取、按需刷新与任务等待；保留兼容回滚路径。
+4. **发布迁移**：发布前使用平台 schema/字典状态执行定向高优先级刷新和最终校验，验证稳定后再讨论清理门店级目录表。已通过 `POST .../publish-preflights` 落地；未来 `publish-jobs` 必须先调用相同服务，不能自行绕过。
+
+当前完成度：第 1～4 步已完成。第 3 步由 `027_product_editor_platform_catalog.sql` 回填平台类目引用并保留旧门店列；编辑器返回统一 cache 元数据，stale 创建低优先级任务并立即返回，expired/missing 创建高优先级任务、最多等待 5 秒后返回 `202`；部分字典的未命中关键词使用独立 `dictionary_search` 任务。第 4 步新增首次发布预检：只接受所选未导入 SKU，先刷新当前 schema，再从已确认草稿识别实际使用的字典；所有 high 任务共用 5 秒窗口，stale 继续 low 后台刷新，最终校验同时检查字典缓存有效期和候选值仍有效。
+
+验收至少覆盖：
+
+- 同平台不同门店读取相同类目、属性和字典记录，不产生门店副本。
+- 13 天 23:59:59、恰好 14 天、恰好 21 天和超过 21 天四个边界行为正确。
+- stale 立即返回旧缓存并只创建一个低优先级任务；expired/missing 复用一个高优先级任务并等待新缓存。
+- queued 低优先级任务可提升，高并发用户不会重复调用 Ozon。
+- 每周树任务、管理员树任务和来源变更任务正确去重。
+- 三种类型属性批次分别准确覆盖 missing+expired、missing+stale+expired、全部活动类型；支持部分失败和准确进度，不自动创建字典任务。
+- “同步全部类型属性”在二次确认前不产生批次、run 或 outbox，另外两个按钮在无命中类型时不能创建空批次。
+- 字典完整/部分状态与查询词补齐不混淆；只有完整同步才能停用消失的旧值。
+- 调整策略后不立即制造全量任务，下一次访问按新阈值生效。
+- Ozon 失败、超时、429 和 Worker 重启均保留上次成功缓存、任务审计与可恢复状态。
+
+## 11. 已确认的产品规则
+
+1. 管理员属性批次有三种范围：missing+expired、missing+stale+expired、全部活动类型；全量批次会刷新 fresh 类型，并使用红色按钮和二次确认。
+2. `age = 21 天` 仍属于 stale/低优先级；只有严格大于 21 天才属于 expired/高优先级。
+3. missing 包括从未同步成功的整个资源，以及 partial 字典中从未成功补齐的具体查询作用域，均按高优先级处理。
+4. expired 数据可以用于保留和展示已有草稿值，但不能作为当前可选 schema/候选值或发布校验事实。
+5. 类目树周期首期固定 7 天；后台只配置类型属性和属性字典的两组新鲜/过期阈值。

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` 语义。

docs/product/ozon-dynamic-attributes-and-sku-form-plan.md

@@ -4,7 +4,7 @@
 
 ## 1. 目标与原则
 
-Ozon 商品的必填属性由 `description_category_id` 与 `type_id` 对应的类目 schema 决定；目标架构中，同一 Ozon 平台的所有门店共用该 schema。编辑器不得为儿童玩具、服装、食品等类目分别硬编码字段，而应使用 Ozon 返回的 `is_required`、`is_aspect`、`dictionary_id`、`is_collection`、`max_value_count`、`type` 与复杂属性信息驱动展示、填报和发布校验。目标参考数据归属见[架构决策](../architecture/platform-product-reference-catalog.md)；当前实现仍读门店级缓存。
+Ozon 商品的必填属性由 `description_category_id` 与 `type_id` 对应的类目 schema 决定；同一 Ozon 平台的所有门店共用该 schema。编辑器不得为儿童玩具、服装、食品等类目分别硬编码字段，而应使用 Ozon 返回的 `is_required`、`is_aspect`、`dictionary_id`、`is_collection`、`max_value_count`、`type` 与复杂属性信息驱动展示、填报和发布校验。当前编辑器已经读取平台级类目、属性和字典缓存；发布链路迁移仍待后续步骤。
 
 页面继续以 Atlas 商品和 SKU 为编辑主体：主要信息保留稳定的商品级字段，Ozon 类目属性按通用属性和 SKU 变体属性拆分。保存草稿允许信息不完整；首次上架必须由服务端按当时有效的类目 schema 重新校验。
 
@@ -65,7 +65,7 @@ SKU 中的 Ozon 必填变体属性同样只在 Label 前显示红色 `*`。父
 3. 同步成功后重新构建动态属性表单。
 4. 页面显示类目路径、商品类型和最后同步时间，并提供失败后的重试入口。
 
-以上描述当前门店级 schema 的获取流程。迁移到平台级参考目录后，直接读取当前平台共享 schema，不叠加门店差异；缺失或过期时由统一后台任务补齐，普通用户不直接触发 Ozon 请求，管理员重试与定时任务共用同一队列。接口字段及草稿外键在 `docs/api/` 更新前不改变。
+以上描述当前门店级 schema 的获取流程。迁移到平台级参考目录后，直接读取当前平台共享 schema，不叠加门店差异；普通用户只请求 Atlas，Atlas 在缓存 stale、expired 或 missing 时创建/复用统一 Worker 任务，不由 API 进程直连 Ozon。14～21 天的旧缓存立即返回并低优先级刷新，严格超过 21 天或未缓存时等待高优先级任务；完整规则见[平台目录缓存刷新方案](../architecture/platform-catalog-cache-refresh-plan.md)。接口字段及草稿外键在 `docs/api/` 更新前不改变。
 
 属性 schema 响应除现有字段外，计划补充：
 

docs/project/HANDOFF.md

@@ -293,7 +293,7 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目
 
 - 类目/商品类型树、类型属性定义和字典候选值归属 `platform_id`，同一平台的全部门店共用，不再按门店复制。Ozon 与未来 Wildberries 等平台分别使用自己的适配器和外部 ID 语义；本阶段**不创建、不读取门店差异层**。
 - 门店连接、卖家凭据、商品/SKU 已填属性、发布状态和错误仍是工作空间业务数据。平台参考目录不保存客户商品、价格、库存或发布事实。
-- 这项平台级能力已经独立落地，但商品编辑器仍使用 `022_store_catalog_cache.sql` 的门店级类目 UUID、属性和字典 API。不得直接删除旧表或把新旧 UUID 混用；编辑器迁移必须通过 Ozon 外部 ID 做双读/回填后再切换。
+- 商品编辑器已由迁移 `027` 和新版 API 切到平台级类目 UUID、属性和字典缓存。`022_store_catalog_cache.sql` 的门店表与列暂时保留为兼容/回滚数据，不得在发布链路迁移完成前删除。
 
 #### 1.33.2 类目树、属性和字典的标识规则
 
@@ -357,12 +357,68 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
 
 1. 调整定时调度公平性：树之后不能等待全部类型属性完成才开始字典；应在属性和字典之间设置配额/轮转，并优先近期使用或管理员选中的类型。
 2. 为超过 10000 项的大字典实现可续传游标或分片同步周期。当前任务会正确标记 `is_complete=false`，但下一次仍从头读取，不能持续推进到第 10001 项以后。
-3. 将商品编辑器由门店级缓存迁移到平台级目录：按 `description_category_id + type_id` 和属性 ID 回填，先双读/兼容保存，再切换外键和 API，最后才讨论清理 `022` 表。
+3. ~~将商品编辑器由门店级缓存迁移到平台级目录。~~ 已由第 3 步完成；后续只在发布迁移和稳定性验证后讨论清理 `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)。
 
+### 1.34 开发进度与交接（2026-09-20）：平台目录刷新方案第 1 步
+
+第 1 步后端基础已完成，尚未开始系统后台页面、商品编辑器和发布链路迁移：
+
+- 新增并实际应用 `025_platform_catalog_refresh_policy.sql`、`026_platform_catalog_refresh_policy_audit.sql`：按平台保存类型属性/字典的 14/21 天默认策略及不可变的阈值修改前后值；按 tree、attributes、dictionary、dictionary_search 保存独立资源状态；为同步 run 增加 high/low 优先级和提升时间；增加管理员属性批次及固定类型快照。没有创建门店级新表，也没有删除旧缓存。
+- 迁移从历史成功 run 回填资源状态。应用后实际回读：Ozon 共有 7365 个活动可发布类型，其中 687 个类型属性 fresh、6678 个 missing，stale/expired 均为 0；另回填 1 个树状态和 1 个字典状态。默认策略已为所有现有平台写入 14/21 天。
+- 平台目录调度器已改为只自动维护每周类目树。类型属性和字典不再进入周期自动候选；属性只从管理员批次中每个平台最多 6 个活动任务地逐步领取，字典保留单项任务。管理员批次支持 `missing_expired`、`missing_stale_expired`、`all` 三种冻结范围。
+- 新增刷新策略、属性状态汇总、批次创建/列表/详情管理 API。相同平台一次只允许一个活动属性批次；空批次返回明确错误；批次允许部分失败。现有树/单属性/单字典接口保持兼容。
+- 平台 run 和独立 BullMQ 队列 `atlas-platform-catalog` 已支持 high/low 优先级；missing/严格超过过期阈值为 high，恰好 21 天仍为 low。低优先级 queued 任务可提升并复用同一 run，不能打断已经 running 的请求；旧 `atlas-dispatch` 暂时保留消费历史平台任务的兼容分支。
+- 平台同步成功会在同一发布事务更新 `last_success_at/is_complete` 并清除错误；失败只记录资源错误，不延长新鲜期或清空上次成功缓存。字典管理读取已改用资源状态判断完整性。
+- 已通过 API/Worker/Database TypeScript 检查、5 项系统管理员参数单元测试和 9 项 Worker 测试；迁移已在真实 PostgreSQL 应用，并用回滚事务验证批次/平台外键。`git diff --check` 通过。
+
+运行态提醒：维护者管理的 API/Worker 进程不会由 AI 重启。若当前 Worker 是修改前启动的旧进程，它仍会执行旧的 24 小时属性候选；需要维护者在检查代码后自行重启 API 和 Worker，新的每周树/无属性字典周期调度才会生效。
+
+第 1 步已经用户确认，随后完成的第 2 步见下一节；此前已有的类目树固定搜索框和展开修复已保留。
+
+### 1.35 开发进度与交接（2026-09-20）：平台目录刷新方案第 2 步
+
+第 2 步系统后台页面已完成，尚未开始商品编辑器和发布链路迁移：
+
+- 「平台类目与属性」页已接入平台刷新策略，可配置类型属性和属性字典各自的新鲜/过期天数；类目树固定 7 天。表单执行 `1..365` 和“过期严格大于新鲜”校验，保存说明明确不会立即创建全量任务。
+- 缓存新鲜度表单现已从主页面移入弹窗；操作区通过“缓存新鲜度设置”按钮打开。保存成功后关闭弹窗并刷新策略、类目及当前属性状态，保存失败时保留弹窗和用户输入。
+- “最近同步任务”的手动刷新按钮现显示请求中的 loading 状态；刷新成功提示“同步任务刷新成功”，失败使用统一 API 错误消息。后台每 5 秒静默轮询仍保持无提示，避免周期性打扰管理员。
+- 类型属性区展示 fresh/stale/expired/missing 汇总以及最近批次。三个操作分别覆盖 missing+expired、missing+stale+expired、全部类型；前两个显示命中数并在 0 时禁用，“同步全部类型属性”为红色危险按钮，必须在含类型数量和耗时提示的二次确认后才请求 API。
+- 批次表展示完成比例、成功/运行/等待/失败数量与最终状态；同平台存在活动批次时禁用新建。页面每 5 秒静默刷新任务和批次，不让操作按钮周期性闪烁加载态。
+- 类目树保留此前完成的固定搜索框和手动展开修复，并在可发布叶子展示类型属性缓存状态。选择类型后，属性卡标题重复显示类型状态；字典属性在表格和候选值 Drawer 中展示独立缓存状态、最近成功时间、完整/部分状态及候选值数量，仍保留单字典手动同步。
+- 最近任务表新增 high/low 优先级以及 weekly、admin_batch、user_access、publish 等触发来源文案。页面主文件只协调状态和请求；刷新策略、属性批次、缓存标签、任务表均拆为独立组件。
+- API 的类目和属性读模型补充最近资源错误及字典新鲜度字段，用于后台观测；没有改变普通商品编辑 API。
+- 浏览器实测：页面无横向溢出；类目搜索可自动展开到匹配叶子；missing/fresh 类型状态正确；fresh 类型属性表和 missing 字典 Drawer 正常；全量同步仅打开危险确认层，验收过程没有创建批次或同步任务。
+
+验证：Web TypeScript 与 production build、API TypeScript/build 和 5 项管理 API 单元测试通过，`git diff --check` 通过。页面在维护者现有 API 上完成浏览器回归；Vite 验收服务使用 5174 并在验收后关闭。API/Worker 未由 AI 启动、重启或停止。
+
+第 2 步已验收，第 3 步完成情况见下一节；第 4 步也已在用户确认后完成，见 1.37。
+
+### 1.36 开发进度与交接（2026-09-20）：平台目录刷新方案第 3 步
+
+- 新增并实际应用 `027_product_editor_platform_catalog.sql`。迁移按 `platform_id + description_category_id + type_id` 将既有 `store_product_category_id` 回填到 `platform_product_category_id`，同步回填未映射属性的原平台类目；旧门店列和三张门店缓存表继续保留，新保存会尽量反写对应门店类目 UUID，便于回滚。
+- 商品编辑器类目树、类型属性和字典全部改读平台级表。切换同平台目标店铺不再清空类目；动态属性 schema 返回 `attribute_id`，字典 API 用该平台属性 UUID 限定候选值，不再只按可能重复的 `dictionary_id` 定位。
+- 普通读取已实现 14/21 天状态机：fresh 直接返回；stale 返回旧缓存并创建/复用 low `user_access` run；expired/missing 创建/复用 high run，API 最多等待 5 秒，未完成则返回 HTTP `202`、空当前选项和 cache 元数据。前端最多轮询 20 次，过期旧值不进入当前控件。
+- 平台级部分字典的本地未命中关键词现在使用独立 `dictionary_search:{attribute_id}:{hash}` 作用域。`platform_catalog_sync_runs` 保存规范化 `search_key`；Worker 调 Ozon 搜索接口，命中值先写入 Atlas，再更新该词的成功状态，不会把局部搜索误标为完整字典。
+- 草稿保存和本地 validation 已改用平台 schema/字典。expired/missing schema 下，只允许原样保留已有属性并保存其他商品字段；类目变化或属性改写会返回刷新中错误。expired/missing 字典不能校验新候选值，旧草稿值仍可保留。
+- 产品 API 契约更新为 `platform_product_category_id`，过渡期仍接受旧 `store_product_category_id` 并通过外部 ID 映射。属性/字典响应统一返回 `cache.status`、最近成功时间、fresh/expire 时间、完整性、刷新 run 和重试间隔。
+- 验证已通过：contracts/API/Worker/Web TypeScript；`product-editor.e2e.test.ts` 与 `platform-catalog-admin.unit.test.ts` 共 13 项；迁移在本地 PostgreSQL 成功执行；`027` 约束和旧引用回填已实际验证。API/Worker 未由 AI 启动、重启或停止。
+
+第 4 步首次发布预检已完成，见下一节。旧门店目录表暂不清理；需要等待真正的 Ozon 发布 job 复用预检服务并完成稳定性验证后另行决策。
+
+### 1.37 开发进度与交接（2026-09-20）：平台目录刷新方案第 4 步
+
+- 新增 `POST /api/product-platform-profiles/{profile_id}/publish-preflights`。请求明确给出本次待首次上架的 `variant_ids`；只接受当前 profile 下 `not_listed` / `failed` 的未删除 SKU，拒绝 imported、submitting、跨商品和已删除 SKU。
+- 发布预检先检查当前 `platform_product_category_id` 的 schema。fresh 直接使用；stale 使用缓存并创建/复用 low `publish` 任务；expired/missing 创建/复用 high `publish` 任务。低优先级 queued 任务在资源过期后复用原 run 并提升为 high。
+- schema 可用后，只从本次 SKU 集合的已确认商品/SKU 属性草稿提取实际使用的字典。未填写的可选字典、其他 SKU 和同类型下未使用字典都不会创建任务；不扫描其他类型，也不使用旧门店目录。
+- 多个 high schema/字典任务共用一个最多 5 秒等待窗口。schema 刷新成功后会基于新 schema 再计算字典依赖；窗口内未完成返回 HTTP `202` 和 `status=refreshing`，客户端可重试同一预检，不能退回过期缓存。
+- 最终本地校验除标题、型号、品牌、必填属性、offer ID、价格、包装和图片外，新增“所用字典缓存未过期且候选 ID 仍为活动值”检查。stale 字典可以完成本次发布校验并在后台刷新；expired/missing 会返回刷新中问题。
+- 预检响应包含 schema 与每个已用字典的统一 cache 元数据，以及本次创建/复用的目录 runs。真正的 `product_publish_job`、发布快照、Ozon `/v3/product/import` 调用和轮询仍未实现；预检 ready 不能解释为已提交或已发布。
+- 代码按目录编排、最终校验、HTTP 入口拆分在独立组件中，没有把逻辑继续堆入 `product-editor.service.ts`。API 集成测试覆盖 stale 的 low publish 任务、expired 的 high 提升、只刷新已用字典和不触达未用字典。
+
 ## 2. 已确认产品决策
 
 | 主题 | 决策 |
@@ -381,7 +437,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
 | 采集 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)。 |
+| 平台商品参考目录 | `platform_id` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面、手动排队、商品编辑器读取和发布预检已实现；真正的 Ozon 发布 job 待开发。 |
 
 ## 3. Ozon 已核对结论
 
@@ -424,12 +480,12 @@ User → Workspace → Membership / Role
 
 下一步建议按以下顺序推进：
 
-> 注意：下面的清单不能覆盖 2026-09-18 的 [Ozon 参考目录决策](../architecture/platform-product-reference-catalog.md)。平台目录、后台和同步基础链路已经实现；现有门店级商品编辑契约在完成兼容迁移前继续生效。
+> 注意：下面的清单不能覆盖 2026-09-18 的 [Ozon 参考目录决策](../architecture/platform-product-reference-catalog.md)。平台目录、后台、同步基础链路和商品编辑器迁移已经实现；旧门店目录只作为兼容/回滚数据保留。
 
 当前执行顺序：
 
-1. 完成平台目录首次预热并修正属性/字典调度公平性和大字典续传；补 PostgreSQL 集成测试与系统管理员浏览器回归。
-2. 按 Ozon 外部 ID 建立新旧目录映射和双读，迁移商品编辑器到平台级类目、属性和候选值；在验证前保留门店级缓存与外键。
+1. 将真正的 `publish-jobs` 创建事务接入已经完成的发布预检服务，固化发布快照后再实现 Ozon `/v3/product/import` 与结果轮询；不得重新实现另一套目录判断。
+2. 完成平台目录首次预热并修正大字典续传；补系统管理员浏览器回归。旧门店目录继续保留，暂不清理。
 3. 在真实采集来源中继续回归候选媒体按需物化，然后完成定价、AI 任务、首次发布和在线商品同步的剩余纵向闭环。
 
 ### 历史计划（仅供追溯）