feat: 开发采集、采集箱和商品编辑功能

2026-08-15 22:17:26 +08:00
parent c61d1a3154
commit 36357843d0
130 changed files with 18005 additions and 12 deletions
@@ -0,0 +1,143 @@
+# Ozon Seller API 文档整理完成
+
+已完成 Ozon Seller API 的核心接口文档整理，涵盖商品发布、管理的完整流程。
+
+## 已完成的文档
+
+### 核心文档（9 个）
+
+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** - 库存管理（必须设置才能上架）
+
+### 待补充（二期）
+
+- **07-import-by-sku.md** - 跟卖（按 SKU 复制 PDP）
+- **08-pictures.md** - 图片更新
+- **10-prices.md** - 价格批量更新
+
+---
+
+## 文档特色
+
+### 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 数据库设计