docs: 更新文档

2026-09-20 15:23:44 +08:00
parent 880e441bc6
commit e0e07be4ea
19 changed files with 164 additions and 312 deletions
@@ -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 尚未实现，且发布预检的树级新鲜度边界仍需在接入前确认或补齐。

 验收至少覆盖：