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,333 @@
+# 类目树查询 API
+
+> 官方文档：https://docs.ozon.ru/api/seller/zh/#operation/DescriptionCategoryAPI_GetTree
+
+---
+
+## 接口信息
+
+| 项 | 值 |
+|---|---|
+| 方法 | POST |
+| 路径 | `/v1/description-category/tree` |
+| 鉴权 | 需要 `Client-Id` + `Api-Key` |
+| 用途 | 获取 Ozon 商品类目树（选择类目后才能发布商品） |
+
+---
+
+## 请求
+
+### 请求体
+
+```json
+{
+  "language": "RU"
+}
+```
+
+### 参数说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| language | string | 可选 | 语言代码，可选值：`DEFAULT`（英文）、`RU`（俄文）、`EN`（英文）、`ZH_HANS`（简体中文）。默认 `DEFAULT` |
+
+---
+
+## 响应
+
+### 成功响应（200）
+
+```json
+{
+  "result": [
+    {
+      "description_category_id": 17033876,
+      "category_name": "Термокружки",
+      "type_id": 97114,
+      "type_name": "Термокружка",
+      "disabled": false,
+      "children": []
+    },
+    {
+      "description_category_id": 17028922,
+      "category_name": "Посуда",
+      "type_id": 0,
+      "type_name": "",
+      "disabled": true,
+      "children": [
+        {
+          "description_category_id": 17033876,
+          "category_name": "Термокружки",
+          "type_id": 97114,
+          "type_name": "Термокружка",
+          "disabled": false,
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| description_category_id | integer | **类目 ID**（发布商品时必填） |
+| category_name | string | 类目名称 |
+| type_id | integer | **商品类型 ID**（发布商品时必填，与 category_id 配对） |
+| type_name | string | 商品类型名称 |
+| disabled | boolean | **是否禁用**。`true` = 不可建品（父类目），`false` = 可建品（末级类目） |
+| children | array | 子类目（递归结构） |
+
+---
+
+## 关键约束
+
+1. **只有末级类目可建品**：`disabled=false` 的类目才能用于发布商品
+2. **必须配对使用**：发布时需同时提供 `description_category_id` + `type_id`
+3. **层级结构**：类目可能有多层嵌套（最多 5-6 层），需递归遍历找到末级
+
+---
+
+## 使用场景
+
+### 场景 1：前端类目选择器
+
+```
+① 请求类目树（language=RU，给俄文用户看）
+② 递归展开树形结构
+③ 用户选择类目后，校验 disabled=false（若 true 则禁止选择或自动展开子级）
+④ 选中后保存 description_category_id + type_id
+```
+
+### 场景 2：服务端缓存
+
+```
+① 启动时拉取类目树（language=DEFAULT，英文字段名便于代码处理）
+② 存入 category_tree 表（见 docs/v2/database.md §2.7）
+③ TTL 24h，过期重拉
+④ 用户选类目时直接查库，不频繁调 API
+```
+
+---
+
+## 示例代码
+
+### Python（服务端缓存）
+
+```python
+import httpx
+from typing import List, Dict, Any
+
+async def fetch_category_tree(
+    client_id: str,
+    api_key: str,
+    language: str = "DEFAULT"
+) -> List[Dict[str, Any]]:
+    """拉取类目树并返回扁平化列表"""
+    headers = {
+        "Client-Id": client_id,
+        "Api-Key": api_key,
+        "Content-Type": "application/json"
+    }
+    
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(
+            "https://api-seller.ozon.ru/v1/description-category/tree",
+            headers=headers,
+            json={"language": language}
+        )
+        resp.raise_for_status()
+        data = resp.json()
+    
+    # 递归扁平化
+    def flatten(nodes: List[Dict], level: int = 0, parent_id: int = 0):
+        flat = []
+        for node in nodes:
+            flat.append({
+                "description_category_id": node["description_category_id"],
+                "parent_id": parent_id,
+                "category_name": node["category_name"],
+                "type_id": node["type_id"],
+                "type_name": node["type_name"],
+                "disabled": node["disabled"],
+                "level": level,
+                "lang": language
+            })
+            if node.get("children"):
+                flat.extend(flatten(
+                    node["children"],
+                    level + 1,
+                    node["description_category_id"]
+                ))
+        return flat
+    
+    return flatten(data.get("result", []))
+```
+
+### TypeScript（前端选择器）
+
+```typescript
+interface CategoryNode {
+  description_category_id: number;
+  category_name: string;
+  type_id: number;
+  type_name: string;
+  disabled: boolean;
+  children: CategoryNode[];
+}
+
+async function fetchCategoryTree(language = 'RU'): Promise<CategoryNode[]> {
+  const resp = await fetch('/api/categories/tree?lang=' + language);
+  const data = await resp.json();
+  return data.result;
+}
+
+// 转为 antd Tree 数据结构
+function toTreeData(nodes: CategoryNode[]): any[] {
+  return nodes.map(node => ({
+    key: `${node.description_category_id}-${node.type_id}`,
+    title: node.category_name,
+    disabled: node.disabled,  // 父类目禁止选择
+    children: node.children.length > 0 ? toTreeData(node.children) : undefined,
+    // 保存原始数据，选中时取用
+    data: {
+      description_category_id: node.description_category_id,
+      type_id: node.type_id
+    }
+  }));
+}
+```
+
+---
+
+## 缓存策略
+
+### 全局缓存（推荐）
+
+```python
+# 类目树与店铺无关，所有店铺共用一份
+# 启动时拉取，存内存 + 数据库
+# TTL 24h（类目变化不频繁）
+
+from functools import lru_cache
+from datetime import datetime, timedelta
+
+_category_tree_cache = None
+_cache_time = None
+
+@lru_cache(maxsize=1)
+async def get_category_tree_cached(language: str = "DEFAULT"):
+    global _category_tree_cache, _cache_time
+    
+    now = datetime.utcnow()
+    if _category_tree_cache and _cache_time and (now - _cache_time) < timedelta(hours=24):
+        return _category_tree_cache
+    
+    # 从任意店铺拉（类目树全局一致）
+    tree = await fetch_category_tree(any_client_id, any_api_key, language)
+    _category_tree_cache = tree
+    _cache_time = now
+    
+    # 同时写数据库
+    await save_to_db(tree)
+    
+    return tree
+```
+
+### 按需更新
+
+```python
+# 用户反馈「找不到某类目」时手动刷新
+async def refresh_category_tree():
+    global _category_tree_cache, _cache_time
+    _category_tree_cache = None
+    _cache_time = None
+    get_category_tree_cached.cache_clear()
+    return await get_category_tree_cached()
+```
+
+---
+
+## 常见问题
+
+### Q1: 类目树很大吗？
+
+**A**: 约 **1-2 万个类目节点**，JSON 约 3-5MB。首次拉取需几秒，后续从缓存读取。
+
+### Q2: 多久更新一次？
+
+**A**: Ozon 不定期新增类目（月级别），建议 **24h TTL + 手动刷新入口**。
+
+### Q3: 不同语言的类目树结构一样吗？
+
+**A**: 结构一致（`description_category_id` / `type_id` 相同），仅 `category_name` / `type_name` 翻译不同。建议：
+- 服务端缓存 `DEFAULT`（英文，便于代码处理）
+- 前端按用户语言拉取 `RU`（俄文，展示用）
+
+### Q4: `type_id=0` 是什么意思？
+
+**A**: 父类目（`disabled=true`）的 `type_id` 为 0，表示该节点不是商品类型，只是分类层级。只有末级类目的 `type_id > 0`。
+
+---
+
+## V2 项目集成
+
+### API 层（已实现）
+
+```python
+# server/api/categories.py
+
+@router.get("/categories/tree")
+async def get_tree(
+    lang: str = Query("RU"),
+    shop_id: str = Query(...),  # 需要店铺凭证
+    db: AsyncSession = Depends(get_db)
+):
+    shop = await get_shop(db, shop_id)
+    tree = await ozon_client.get_category_tree(
+        shop.client_id_dec,
+        shop.api_key_dec,
+        lang
+    )
+    return {"result": tree}
+```
+
+### 前端（待实现）
+
+```tsx
+// studio/src/pages/product/components/CategoryPicker.tsx
+
+import { Tree } from 'antd';
+import { useEffect, useState } from 'react';
+
+export function CategoryPicker({ shopId, onChange }) {
+  const [treeData, setTreeData] = useState([]);
+  
+  useEffect(() => {
+    fetch(`/api/categories/tree?shop_id=${shopId}&lang=RU`)
+      .then(r => r.json())
+      .then(data => setTreeData(toTreeData(data.result)));
+  }, [shopId]);
+  
+  return (
+    <Tree
+      treeData={treeData}
+      onSelect={(keys, { node }) => {
+        if (!node.disabled) {
+          onChange(node.data);  // { description_category_id, type_id }
+        }
+      }}
+    />
+  );
+}
+```
+
+---
+
+## 相关文档
+
+- [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 —— 类目字典缓存策略