docs: 更新文档

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

@@ -164,6 +164,8 @@ expired/missing ─────→ 高优先级刷新 → 短暂等待
 - 发布使用到的字典值必须存在于该平台、类型和属性作用域的有效缓存。相关字典 expired/missing 时先刷新对应字典或目标查询作用域，不刷新该类型下所有字典。
 - Ozon 最终仍可能返回平台校验错误；这类错误按商品/门店记录，必要时将对应平台参考资源标记为需要重新检查，但不能自动生成门店差异层。
 
+当前实现的 `publish-preflights` 已覆盖类型属性和实际使用字典的新鲜度，但类目树仍只依赖固定每周同步和本地节点 `is_active`。预检尚未读取树级新鲜度或因树过期创建同步任务；本地类目不存在、已停用或跨平台时返回 Atlas 的 `422 CATEGORY_INVALID`。真正的 Ozon 发布 job 接入前，应明确补齐树级新鲜度保护，或以验证结果正式确认“每周全量同步 + 本地活动状态”就是接受的发布边界。
+
 ## 8. 系统后台调整
 
 「平台类目与属性」页面保留现有平台选择、同步来源、类目树、属性和字典浏览能力，并调整为：
@@ -190,6 +192,8 @@ expired/missing ─────→ 高优先级刷新 → 短暂等待
 
 设置保存后立即用于后续读取判断，但不主动扫描并创建数千任务。例如把过期天数从 30 改为 21 后，只有下次用户读取、发布校验或管理员批次触达该资源时才创建任务。修改必须记录操作者、修改时间和前后值。
 
+管理页不直接常驻展示这组表单。操作区使用“缓存新鲜度设置”按钮打开弹窗；保存成功后关闭弹窗并刷新策略、类目及当前属性状态，失败时保留弹窗和用户输入。
+
 ### 8.3 状态展示
 
 管理页至少展示：
@@ -200,9 +204,11 @@ expired/missing ─────→ 高优先级刷新 → 短暂等待
 - 字典的相同新鲜度状态、完整/部分状态、候选值数量和最近错误；
 - 高低优先级、触发来源（weekly/manual/admin_batch/user_access/publish）和任务复用关系。
 
-## 9. 建议的数据与契约调整
+“最近同步任务”的手动刷新按钮在请求期间展示 loading；成功显示 message，失败展示统一 API 错误。每 5 秒自动轮询保持静默，不能反复弹出提示或使按钮周期性闪烁。
 
-确认后至少需要补充以下模型，具体 DDL 和字段名在实现阶段冻结：
+## 9. 已实施的数据与契约调整
+
+迁移 `025`～`027` 与相应 contracts/API 已落地以下模型：
 
 1. 平台同步策略：保存属性、字典的新鲜和过期天数以及审计字段。
 2. 资源同步状态：按 tree、类型属性、属性字典和字典搜索作用域保存 `last_success_at`、`is_complete`、最新任务及错误；不能仅依赖数据行的 `updated_at` 推断是否成功检查过。
@@ -210,7 +216,7 @@ expired/missing ─────→ 高优先级刷新 → 短暂等待
 4. 任务优先级与触发来源：区分 high/low 及 weekly、manual、admin_batch、user_access、publish。
 5. 商品编辑引用：从门店类目 UUID 迁移为平台类目 UUID；属性和值仍按当前商品/SKU 草稿保存，但校验引用平台 schema。
 
-普通产品读取响应建议统一带：
+普通产品读取响应现统一带：
 
 ```json
 {
@@ -228,18 +234,18 @@ expired/missing ─────→ 高优先级刷新 → 短暂等待
 }
 ```
 
-管理 API 需要增加同步策略读取/修改和类型属性批次创建/读取；现有单项 `POST .../syncs` 保留给树和字典。最终端点、状态码和错误码必须在实现前更新 [`platform-catalog-admin.md`](../api/platform-catalog-admin.md) 与 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md)。
+管理 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 后台刷新，最终校验同时检查字典缓存有效期和候选值仍有效。
+当前完成度：第 1～4 步已完成。第 3 步由 `027_product_editor_platform_catalog.sql` 回填平台类目引用并保留旧门店列；编辑器返回统一 cache 元数据，stale 创建低优先级任务并立即返回，expired/missing 创建高优先级任务、最多等待 5 秒后返回 `202`；部分字典的未命中关键词使用独立 `dictionary_search` 任务。第 4 步新增首次发布预检：只接受所选未导入 SKU，先刷新当前 schema，再从已确认草稿识别实际使用的字典；所有 high 任务共用 5 秒窗口，stale 继续 low 后台刷新，最终校验同时检查字典缓存有效期和候选值仍有效。真正的 Ozon 发布 job 尚未实现，且发布预检的树级新鲜度边界仍需在接入前确认或补齐。
 
 验收至少覆盖：
 

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

@@ -25,9 +25,9 @@ Atlas 本阶段明确采用**平台级参考数据**：同一 `platform_id` 下
 
 统一的后台同步服务按 `platform_id` 负责定时任务、首次缺失时的补齐和管理员手动请求。三种触发方式都创建有权限校验、幂等去重的 `platform_catalog_sync_runs + platform_catalog_outbox_events`；这是不带 `workspace_id` 的全局任务事实，不能借用租户 `operations/outbox_events`。Worker 通过平台适配器读取服务端安全存储的参考源凭据并调用对应平台。浏览器、日志、run 和 outbox 载荷不包含 API Key。管理员手动同步不得在 HTTP 请求内直接访问平台或绕过同一套限流、审计与事务发布流程。
 
-1. **同步来源**：每个平台分别配置 Atlas 专用的参考源凭据及适配器；Ozon 首期使用专用参考门店凭据作为技术采集身份，而非普通客户工作空间门店。设置最小授权、密钥轮换、失效告警与备用源，不能未经授权借用客户门店密钥。若暂无专用凭据，保持现有门店级链路，待来源配置完成后迁移。
+1. **同步来源**：每个平台分别配置 Atlas 专用的参考源凭据及适配器；Ozon 首期使用专用参考门店凭据作为技术采集身份，而非普通客户工作空间门店。设置最小授权、密钥轮换、失效告警与备用源，不能未经授权借用客户门店密钥。若暂无专用凭据，平台同步任务保持不可执行，读路径按 stale/expired/missing 规则返回；不得回退到客户门店级目录或临时借用某个用户的密钥。
 2. **基线调度（当前代码事实）**：类目树最近成功时间达到 7 天后由调度器创建低优先级周任务；管理员仍可手动创建高优先级树任务。类型属性和字典已经退出周期自动候选，类型属性只从管理员显式创建的三种批次中逐批领取，字典只保留单项手动入口。普通商品读路径已按 14/21 天执行 fresh/stale/expired/missing 状态机，并创建或复用 user_access 平台任务。
-3. **管理员页面**：按平台展示参考源状态、树、属性、字典候选值、最后成功时间、失败详情、排队任务和「同步类目树 / 指定类目属性 / 指定字典」操作。手动动作必须受系统管理员权限控制、记录操作者，并返回异步任务；页面不展示密钥明文。当前实现位于 `/system/platform-catalog`，全局系统管理员授权独立于工作空间角色。
+3. **管理员页面**：按平台展示参考源状态、树、属性、字典候选值、最后成功时间、失败详情和排队任务；提供类目树手动同步、三种范围的类型属性批次和单字典同步。缓存新鲜度设置由操作按钮打开弹窗，最近任务手动刷新有 loading 与成功/失败提示，5 秒自动轮询保持静默。所有手动动作受系统管理员权限控制、记录操作者并返回异步任务；页面不展示密钥明文。当前实现位于 `/system/platform-catalog`，全局系统管理员授权独立于工作空间角色。
 4. **读路径**：正常用户只读 Atlas 缓存。首次缺失时可排队补齐并显示准备中；已有数据过期时优先提供上次成功快照并后台更新。不能在每次打开编辑器或下拉框时同步请求 Ozon。大字典搜索按规范化关键词及上述字典作用域共享缓存，并去重并发补齐。
 5. **原子性与监控**：P0 按平台及树、类型属性、字典作用域在单事务内 upsert，提交前读取方继续看到旧数据；失败保留上次成功缓存。仅在确认完整分页完成后才处理消失的字典值，部分同步记录 `is_complete=false`。当前尚未实现不可变版本快照、内容哈希、`next_refresh_at`、连续失败告警和异常删减保护，这些属于上线前可靠性加固，不能在文档中误记为已完成。
 
@@ -43,4 +43,4 @@ Ozon 字典分页每次最多 2000 个值；[搜索接口](https://docs.ozon.ru/
 
 `022_store_catalog_cache.sql` 的门店级表和 profile 的 `store_product_category_id` 仍保留为兼容/回滚数据，但商品编辑器不再读取它们。当前事实来源是平台级类目、属性和 `platform_catalog_dictionary_values`。
 
-迁移 `024`～`026` 建立平台参考来源、候选值、同步任务、策略和资源状态；`027_product_editor_platform_catalog.sql` 以 Ozon 外部类目/类型 ID 回填商品的 `platform_product_category_id`，并为部分字典增加关键词搜索任务作用域。旧门店列和表暂不删除，新保存会尽量反写可映射的门店类目 UUID，供回滚使用。清理旧表必须在发布链路迁移、稳定性验证和维护者批准后另行执行。Wildberries 等新平台应新增平台适配器及自己的外部 ID 映射，不复用 Ozon 的 `description_category_id + type_id` 语义。
+迁移 `024`～`026` 建立平台参考来源、候选值、同步任务、策略和资源状态；`027_product_editor_platform_catalog.sql` 以 Ozon 外部类目/类型 ID 回填商品的 `platform_product_category_id`，并为部分字典增加关键词搜索任务作用域。旧门店列和表暂不删除，新保存会尽量反写可映射的门店类目 UUID，供回滚使用。清理旧表必须等真正的 Ozon 发布 job 复用平台预检、完成稳定性验证并取得维护者批准后另行执行。Wildberries 等新平台应新增平台适配器及自己的外部 ID 映射，不复用 Ozon 的 `description_category_id + type_id` 语义。

docs/architecture/product-domain-data-model.md

@@ -16,7 +16,7 @@
 
 `products` / `product_variants` 只服务采集箱商品，保存来源、采购和跨平台可复用资料。`platform_listings` 则是目标平台、目标门店的实际商品镜像；它不能跨平台或跨门店复用，即使它关联了 Atlas SKU。`product_platform_profiles.market_code` 表示当前平台业务上下文，首期取平台默认 `RU`，不从门店派生。
 
-类目/商品类型、属性定义和字典候选值是待迁移的**平台级**参考数据：同一平台所有门店共用，不跨 Ozon、Wildberries 等平台混用，也不在本阶段维护门店差异层。门店连接与商品/SKU 已填值仍按工作空间隔离。现有 `022_store_catalog_cache.sql` 的门店级缓存和 profile 外键继续有效，目标模型及迁移边界见 [`platform-product-reference-catalog.md`](./platform-product-reference-catalog.md)。
+类目/商品类型、属性定义和字典候选值已经迁移为**平台级**参考数据：同一平台所有门店共用，不跨 Ozon、Wildberries 等平台混用，也不在本阶段维护门店差异层。门店连接与商品/SKU 已填值仍按工作空间隔离。迁移 `024`～`027` 已建立平台参考源、目录任务、刷新策略和商品 profile 的平台类目引用；`022_store_catalog_cache.sql` 的门店级缓存及旧 profile 外键只为兼容和回滚保留，不再作为商品编辑、保存校验或发布预检的事实来源。完整边界见 [`platform-product-reference-catalog.md`](./platform-product-reference-catalog.md)。
 
 ## 2. 关键关系与状态