docs: 更新文档

2026-09-20 15:23:44 +08:00
parent 880e441bc6
commit e0e07be4ea
19 changed files with 164 additions and 312 deletions
@@ -1,143 +1,34 @@
-# Ozon Seller API 文档整理完成
+# Ozon Seller API 文档状态摘要

-已完成 Ozon Seller API 的核心接口文档整理，涵盖商品发布、管理的完整流程。
+> 本文件只汇总当前仓库中的 Ozon 资料和 Atlas 实施状态，不代表 Ozon 官方接口已经全部接入。官方行为以各接口文档与 Ozon 官方文档为准，Atlas 实现进度以 [`../../project/HANDOFF.md`](../../project/HANDOFF.md) 为准。

-## 已完成的文档
+## 已整理资料

-### 核心文档（9 个）
+| 文档 | 主题 | Atlas 当前状态 |
+|---|---|---|
+| [01-authentication.md](./01-authentication.md) | Client-Id、Api-Key 和错误处理 | 平台参考源凭据已由系统管理员配置并仅供 Worker 使用 |
+| [02-category-tree.md](./02-category-tree.md) | 类目/商品类型树 | 平台级共享缓存已实现；每 7 天自动同步并支持管理员手动同步 |
+| [03-category-attributes.md](./03-category-attributes.md) | 类型属性与字典值 | 平台级缓存、14/21 天状态机、管理员批次、按需刷新和发布预检已实现 |
+| [04-product-import.md](./04-product-import.md) | `/v3/product/import` | 仅作为外部接口资料；Atlas 真正的发布 job 尚未实现 |
+| [05-product-info.md](./05-product-info.md) | 商品信息查询 | 资料文档；实现状态以在线商品模块交接为准 |
+| [06-product-list.md](./06-product-list.md) | 商品列表 | 资料文档；仓库同步 Worker 尚未完成 |
+| [09-stocks.md](./09-stocks.md) | 库存管理 | 资料文档；不属于当前平台目录与首次发布预检范围 |

-1. **README.md** - 总览与快速索引
-2. **01-authentication.md** - 鉴权方式、Base URL、错误码、限流
-3. **02-category-tree.md** - 类目树查询（选择类目）
-4. **03-category-attributes.md** - 类目属性与字典值（属性映射）
-5. **04-product-import.md** - 商品导入/创建/更新（核心接口）
-6. **05-product-info.md** - 商品详情查询（审核状态、图片、属性）
-7. **06-product-list.md** - 商品列表分页（ID 收集、批量查询）
-8. **09-stocks.md** - 库存管理（必须设置才能上架）
+跟卖、独立图片更新和价格批量更新尚未形成当前仓库文档。

-### 待补充（二期）
+## Atlas 当前目录与发布边界

- **07-import-by-sku.md** - 跟卖（按 SKU 复制 PDP）
- **08-pictures.md** - 图片更新
- **10-prices.md** - 价格批量更新
+1. 类目树、类型属性和字典候选值按 `platform_id` 维护，同平台所有门店共享；本阶段没有门店差异层。
+2. 类目树固定每 7 天自动同步。类型属性和字典不做周期性全量扫描，由管理员操作、普通用户访问或发布预检触发 Worker 任务。
+3. 类型属性和字典默认 14 天内 fresh、14～21 天（含 21 天）stale、严格超过 21 天 expired；missing/expired 使用高优先级任务，stale 使用低优先级任务。
+4. `POST /api/product-platform-profiles/{profile_id}/publish-preflights` 已实现，只刷新当前类型和所选 SKU 实际使用的字典，并执行本地发布校验。
+5. 真正的 `product_publish_job`、发布快照、Ozon `/v3/product/import` 提交和结果轮询尚未实现；预检 `ready` 不表示商品已经提交或发布。
+6. 发布预检目前只校验本地类目仍活动，尚未判断整棵类目树缓存是否过期；该边界需在真正发布 job 接入前确认或补齐。

---
+## 当前应阅读的实现文档

-## 文档特色
-
-### 1. 完整的代码示例
- Python（服务端）示例
- TypeScript（前端）示例
- 实际可运行的代码片段
-
-### 2. V2 项目集成指引
- 每个文档都包含"V2 项目集成"章节
- API 层实现示例（对齐 server/ 结构）
- 前端组件示例（对齐 studio/ 结构）
-
-### 3. 最佳实践与常见问题
- 缓存策略
- 错误处理
- 性能优化
- 分页/批量操作
-
-### 4. 实用场景
- 发布流程（端到端）
- 属性映射工作流
- 库存同步策略
- 审核状态检查
-
---
-
-## 核心流程速查
-
-### 完整发布流程
-
-```
-① 获取类目树 → 选择类目
-   POST /v1/description-category/tree
-
-② 获取类目属性 → 映射属性
-   POST /v1/description-category/attribute
-   POST /v1/description-category/attribute/values/search
-
-③ 组装请求体 → 发布商品
-   POST /v3/product/import → task_id
-
-④ 轮询状态 → 获取 product_id
-   POST /v1/product/import/info → status=imported
-
-⑤ 设置库存（必须）
-   POST /v2/products/stocks → 商品上架
-
-⑥ 查询详情（可选）
-   POST /v3/product/info/list → 审核状态/图片/库存
-```
-
-### 关键约束总结
-
-1. **类目**：只有末级类目（`disabled=false`）可建品
-2. **必填字段**：name/description/category/price/尺寸重量/offer_id/images
-3. **图片 URL**：必须 https 公网直链
-4. **属性**：`is_required=true` 的必须填写
-5. **异步任务**：`/import` 返回 task_id，需轮询状态
-6. **库存必须设置**：不设置库存 = 商品不可购买
-
---
-
-## 与 V2 项目的对应关系
-
-| Ozon API | V2 后端 API | V2 前端页面 | 状态 |
-|---|---|---|---|
-| `/description-category/tree` | `/api/categories/tree` | CategoryPicker | ✅ 已建 |
-| `/description-category/attribute` | `/api/categories/{id}/attributes` | AttributeMapper | ✅ 已建 |
-| `/attribute/values` | `/api/categories/attribute/{id}/values` | - | ✅ 已建 |
-| `/v3/product/import` | `/api/products/{id}/publish` | PublishPanel | ✅ 已建 |
-| `/v1/product/import/info` | (background poll) | - | ✅ 已建 |
-| `/v3/product/info/list` | `/api/products/{id}/ozon-detail` | OzonStatusBadge | 🟡 待建 |
-| `/v3/product/list` | `/api/products/sync-from-ozon` | SyncButton | 🟡 待建 |
-| `/v2/products/stocks` | `/api/products/{id}/set-stock` | StockPanel | 🟡 待建 |
-
---
-
-## 使用建议
-
-### 阅读顺序（新接入）
-
-1. **01-authentication.md** - 了解鉴权与基础
-2. **04-product-import.md** - 核心接口，先看这个
-3. **02-category-tree.md** - 类目选择
-4. **03-category-attributes.md** - 属性映射（难点）
-5. **09-stocks.md** - 库存设置（必须）
-6. 其他按需查阅
-
-### 开发时查阅
-
- 看接口契约 → 查对应章节的"请求/响应"
- 看错误处理 → 查"常见错误"章节
- 看集成方式 → 查"V2 项目集成"章节
- 看最佳实践 → 查"使用场景"或"最佳实践"章节
-
---
-
-## 下一步
-
-### 立即可用
-现有 9 个文档已覆盖 V2 项目一期的所有核心接口，可立即用于：
- 服务端 `ozon_client.py` 开发
- API 端点实现参考
- 前端组件开发参考
-
-### 二期补充
-需要时再补充：
- 跟卖（import-by-sku）
- 图片单独更新
- 价格批量更新
-
---
-
-## 相关文档
-
- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) - V2 发布集成方案（与本文档配套）
- [docs/v2/api.md](../v2/api.md) - V2 后端 API 设计
- [docs/v2/database.md](../v2/database.md) - V2 数据库设计
+- [平台商品参考目录](../../architecture/platform-product-reference-catalog.md)
+- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md)
+- [平台类目与属性管理 API](../../api/platform-catalog-admin.md)
+- [商品编辑与发布 API](../../api/product-editor-and-publishing.md)
+- [项目交接](../../project/HANDOFF.md)