docs: 更新文档

2026-09-20 15:23:44 +08:00
parent 880e441bc6
commit e0e07be4ea
19 changed files with 164 additions and 312 deletions
@@ -172,6 +172,8 @@ async def fetch_category_tree(

 ### TypeScript（前端选择器）

+> 以下嵌套 `CategoryNode` 和 `/api/categories/tree` 是早期资料中的概念示例，不是当前 Atlas 联调契约。当前商品编辑器从 `GET /api/product-platform-profiles/{profile_id}/category-options` 读取带 `parent_id` 的平台级扁平节点，再在前端重建树；请以[商品编辑与发布 API](../../api/product-editor-and-publishing.md)为准。
+
 ```typescript
 interface CategoryNode {
  description_category_id: number;
@@ -213,7 +215,7 @@ function toTreeData(nodes: CategoryNode[]): any[] {

 ## 缓存策略

-目标方案见 [`platform-product-reference-catalog.md`](../../architecture/platform-product-reference-catalog.md)：每个平台分别维护共享目录；定时自动同步与系统管理员手动触发共用异步任务、原子版本切换和失败保留旧版；前端只读 Atlas 缓存。当前运行中的门店级同步仍见下方「Atlas 当前集成」，不能把目标方案当作已经上线。
+Atlas 已按 [`platform-product-reference-catalog.md`](../../architecture/platform-product-reference-catalog.md) 为每个平台分别维护共享目录：定时自动同步与系统管理员手动触发共用异步任务，失败保留上次成功版本；商品编辑器只读 Atlas 平台缓存。同平台的门店不再各自复制类目树，本阶段也不维护门店差异层。

 ---

@@ -225,11 +227,11 @@ function toTreeData(nodes: CategoryNode[]): any[] {

 ### Q2: 多久更新一次？

-**A**: Ozon 接口未规定 Atlas 的缓存 TTL。目标架构建议由后台每日检查树，并提供管理员手动排队同步入口；间隔可按运行量调整，见[架构决策](../../architecture/platform-product-reference-catalog.md)。
+**A**: Ozon 接口未规定 Atlas 的缓存 TTL。Atlas 固定在最近一次成功后 7 天自动同步完整树，并提供系统管理员手动排队同步入口；失败不会更新成功时间或清空旧树。

 ### Q3: 不同语言的类目树结构一样吗？

-**A**: 接口支持语言参数，不应未经验证就假定各语言的 ID 和翻译映射完全相同。当前 Worker 为每个门店缓存 `ZH_HANS`；目标是由 Ozon 平台参考源统一缓存该语言，同平台所有门店共用。前端不能携带门店密钥直连 Ozon。
+**A**: 接口支持语言参数，不应未经验证就假定各语言的 ID 和翻译映射完全相同。当前 Worker 使用 Ozon 平台参考源统一缓存 `ZH_HANS`，同平台所有门店共用。前端不能携带平台或门店密钥直连 Ozon。

 ### Q4: `type_id=0` 是什么意思？

@@ -239,16 +241,18 @@ function toTreeData(nodes: CategoryNode[]): any[] {

 ## Atlas 当前集成

- **Worker**：以门店凭证调用 Ozon，递归持久化完整 `children` 树及父子关系；缓存命中时不重复调用 Ozon。
- **API**：按当前目标门店返回缓存的扁平节点（包含 `parent_id`）；不会将 `Client-Id` 或 `Api-Key` 返回给浏览器。
+- **Worker**：使用系统后台配置的平台参考源凭据调用 Ozon，递归持久化完整 `children` 树及父子关系；同一平台活动任务按作用域合并。
+- **API**：按当前平台返回缓存的扁平节点（包含 `parent_id`）；不会将 `Client-Id` 或 `Api-Key` 返回给浏览器。
 - **前端**：根据 `parent_id` 重建任意深度的 Cascader；目录可展开，只有可发布的叶子能写入商品草稿。
 - **调试**：若需要查看 Ozon 原始响应，应由受权限保护的服务端调试能力获取并脱敏展示；浏览器不得直接用门店密钥请求 Ozon。
- **迁移目标**：平台级共享目录和统一异步管理同步尚未实现；本阶段不维护门店差异层，见[架构决策](../../architecture/platform-product-reference-catalog.md)。
+- **同步维护**：完整树每 7 天自动同步，也可由系统管理员手动触发；树任务不自动展开为所有类型属性或字典任务。
+- **发布边界**：当前发布预检校验所选本地类目仍活动，但尚未对树级新鲜度创建刷新任务；该边界需在真正发布 job 接入前确认或补齐。

 ---

 ## 相关文档

 - [03-category-attributes.md](./03-category-attributes.md) —— 获取类目属性
- [docs/v2/database.md](../v2/database.md) §2.7 —— `category_tree` 表结构
- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) §3 —— 类目字典缓存策略
+- [平台商品参考目录](../../architecture/platform-product-reference-catalog.md) —— 平台级数据归属
+- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md) —— 每周树同步和属性/字典按需刷新
+- [商品编辑与发布 API](../../api/product-editor-and-publishing.md) —— 编辑器类目读取和发布预检