# 商品列表查询 API

> 官方文档：https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_GetProductListV3

---

## 接口信息

| 项 | 值 |
|---|---|
| 方法 | POST |
| 路径 | `/v3/product/list` |
| 鉴权 | 需要 `Client-Id` + `Api-Key` |
| 用途 | 分页查询商品列表（支持筛选、排序） |

---

## 1. 请求

### 请求体

```json
{
  "filter": {
    "offer_id": ["MY-THERMOS-001"],
    "product_id": [987654321],
    "visibility": "ALL"
  },
  "last_id": "",
  "limit": 100
}
```

### 参数说明

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| filter | object | 可选 | 筛选条件 |
| filter.offer_id | array | 可选 | 货号数组 |
| filter.product_id | array | 可选 | Ozon 商品 ID 数组 |
| filter.visibility | string | 可选 | 可见性：`ALL`（全部）/ `VISIBLE`（可见）/ `INVISIBLE`（不可见）/ `EMPTY_STOCK`（无库存）。默认 `ALL` |
| **last_id** | string | 可选 | **分页游标**（上一页最后一个商品的 ID），首页传空字符串 `""` |
| **limit** | integer | 可选 | 每页数量，最大 **1000**，默认 100 |

---

## 2. 响应

### 成功响应（200）

```json
{
  "result": {
    "items": [
      {
        "product_id": 987654321,
        "offer_id": "MY-THERMOS-001"
      },
      {
        "product_id": 987654322,
        "offer_id": "MY-THERMOS-002"
      }
    ],
    "total": 256,
    "last_id": "bnVtYmVyMjo5ODc2NTQzMjI="
  }
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 商品列表（**仅基本字段**：product_id + offer_id） |
| total | integer | 商品总数 |
| **last_id** | string | **下一页游标**（Base64 编码，传给下次请求） |

⚠️ **注意**：此接口**仅返回 product_id 和 offer_id**，不返回名称/价格/图片等详情。要获取完整信息，需再调 `/v3/product/info/list`。

---

## 3. 分页示例

### 游标分页（推荐）

```python
async def fetch_all_products(visibility="ALL"):
    """拉取所有商品（游标分页）"""
    all_items = []
    last_id = ""
    
    while True:
        resp = await ozon_client.get_product_list(
            filter={"visibility": visibility},
            last_id=last_id,
            limit=1000  # 单次最多 1000
        )
        
        items = resp["result"]["items"]
        all_items.extend(items)
        
        # 无更多数据
        if not resp["result"].get("last_id"):
            break
        
        last_id = resp["result"]["last_id"]
    
    return all_items
```

### 分批处理

```python
async def process_products_in_batches(batch_size=100):
    """分批处理商品（避免一次拉全部）"""
    last_id = ""
    
    while True:
        resp = await ozon_client.get_product_list(
            last_id=last_id,
            limit=batch_size
        )
        
        items = resp["result"]["items"]
        if not items:
            break
        
        # 处理当前批次
        await process_batch(items)
        
        last_id = resp["result"].get("last_id")
        if not last_id:
            break
```

---

## 4. 获取完整信息

### 方法 A：批量查详情（推荐）

```python
async def fetch_products_with_detail(visibility="ALL"):
    """拉取商品列表 + 完整信息"""
    # 1. 拉列表（仅 ID）
    list_resp = await ozon_client.get_product_list(
        filter={"visibility": visibility},
        limit=1000
    )
    
    items = list_resp["result"]["items"]
    product_ids = [item["product_id"] for item in items]
    
    # 2. 批量查详情（每次最多 100 个）
    details = []
    for i in range(0, len(product_ids), 100):
        batch = product_ids[i:i+100]
        detail_resp = await ozon_client.get_product_info(
            product_id=batch
        )
        details.extend(detail_resp["result"]["items"])
    
    return details
```

### 方法 B：按需查详情

```python
# 先列表，用户点击某个商品时再查详情
products = await ozon_client.get_product_list(limit=100)

# 用户点击 product_id=987654321
detail = await ozon_client.get_product_info(product_id=[987654321])
```

---

## 5. 筛选条件详解

### visibility 筛选

| 值 | 含义 | 使用场景 |
|---|---|---|
| **ALL** | 全部商品 | 管理后台（查看所有） |
| **VISIBLE** | 可见商品（上架） | 前台展示的商品 |
| **INVISIBLE** | 不可见商品（下架/草稿） | 待上架/审核失败/归档 |
| **EMPTY_STOCK** | 无库存商品 | 补货提醒 |

### 示例

```python
# 查询所有上架商品
visible = await ozon_client.get_product_list(
    filter={"visibility": "VISIBLE"},
    limit=1000
)

# 查询无库存商品（需补货）
empty_stock = await ozon_client.get_product_list(
    filter={"visibility": "EMPTY_STOCK"},
    limit=100
)
```

---

## 6. 性能对比

### `/v3/product/list` vs `/v3/product/info/list`

| 维度 | `/v3/product/list` | `/v3/product/info/list` |
|---|---|---|
| 返回字段 | 仅 product_id + offer_id | 完整字段（图片/属性/状态） |
| 单次数量 | 最多 **1000** | 最多 **100** |
| 响应速度 | 快（字段少） | 慢（字段多） |
| 适用场景 | 列表/分页/ID 收集 | 详情查询/更新前读取 |

**策略**：
1. 先用 `/list` 拉 ID 列表（快）
2. 再用 `/info/list` 批量查详情（按需，100 个一批）

---

## 7. 与本地数据库同步

### 场景：回填 product_id

```python
async def sync_product_ids():
    """发布后回填 product_id（用 offer_id 匹配）"""
    # 1. 从数据库取所有「已发布但无 product_id」的商品
    local_products = await db.execute(
        select(Product)
        .where(
            Product.stage == "published",
            Product.ozon_product_id.is_(None),
            Product.offer_id.isnot(None)
        )
    )
    local_products = local_products.scalars().all()
    
    if not local_products:
        return
    
    offer_ids = [p.offer_id for p in local_products]
    
    # 2. 从 Ozon 查询这些 offer_id 的 product_id
    ozon_items = []
    for i in range(0, len(offer_ids), 100):
        batch = offer_ids[i:i+100]
        resp = await ozon_client.get_product_info(offer_id=batch)
        ozon_items.extend(resp["result"]["items"])
    
    # 3. 回填到数据库
    ozon_map = {item["offer_id"]: item["id"] for item in ozon_items}
    
    for p in local_products:
        if p.offer_id in ozon_map:
            p.ozon_product_id = ozon_map[p.offer_id]
    
    await db.commit()
```

### 场景：定期同步状态

```python
async def sync_product_states():
    """定期同步商品状态（审核状态/库存/可见性）"""
    # 1. 拉取所有 Ozon 商品 ID
    ozon_resp = await ozon_client.get_product_list(limit=1000)
    ozon_ids = [item["product_id"] for item in ozon_resp["result"]["items"]]
    
    # 2. 批量查详情
    details = []
    for i in range(0, len(ozon_ids), 100):
        batch = ozon_ids[i:i+100]
        resp = await ozon_client.get_product_info(product_id=batch)
        details.extend(resp["result"]["items"])
    
    # 3. 更新本地数据库
    for item in details:
        await db.execute(
            update(Product)
            .where(Product.ozon_product_id == item["id"])
            .values(
                stage="published" if item["visible"] else "failed",
                # 可同步更多字段：价格/库存/审核状态
            )
        )
    
    await db.commit()
```

---

## 8. 常见问题

### Q1: 为什么 `/list` 只返回 ID？

**A**: 性能考虑。商品列表可能有**数万条**，返回完整字段会很慢。设计思路：
1. 先快速拉 ID 列表（轻量）
2. 前端展示分页，只查当前页的详情
3. 或后台批量拉详情，按需处理

### Q2: 如何获取商品总数？

**A**: 响应的 `total` 字段。但注意：
- `total` 是当前筛选条件下的总数
- 不保证精确（可能略有延迟）

### Q3: 游标分页与偏移分页的区别？

**A**: 
- **游标分页**（last_id）：适合全量遍历，性能稳定
- **偏移分页**（offset）：Ozon 不支持（无 offset 参数）

### Q4: 多久同步一次？

**A**: 建议策略：
- 发布后立即查询（回填 product_id）
- 定期同步（每天一次，更新状态/库存）
- 用户主动刷新（按需实时查询）

---

## 9. V2 项目集成

### API 层（待实现）

```python
# server/api/products.py

@router.get("/products/sync-from-ozon")
async def sync_from_ozon(
    shop_id: str = Query(...),
    db: AsyncSession = Depends(get_db)
):
    """从 Ozon 同步商品列表（回填 product_id + 状态）"""
    shop = await get_shop(db, shop_id)
    
    # 1. 拉取 Ozon 商品列表
    ozon_items = []
    last_id = ""
    
    while True:
        resp = await ozon_client.get_product_list(
            shop.client_id_dec,
            shop.api_key_dec,
            last_id=last_id,
            limit=1000
        )
        
        items = resp["result"]["items"]
        ozon_items.extend(items)
        
        last_id = resp["result"].get("last_id")
        if not last_id:
            break
    
    # 2. 批量查详情
    product_ids = [item["product_id"] for item in ozon_items]
    details = []
    
    for i in range(0, len(product_ids), 100):
        batch = product_ids[i:i+100]
        detail_resp = await ozon_client.get_product_info(
            shop.client_id_dec,
            shop.api_key_dec,
            product_id=batch
        )
        details.extend(detail_resp["result"]["items"])
    
    # 3. 更新本地数据库
    updated = 0
    for item in details:
        result = await db.execute(
            update(Product)
            .where(Product.offer_id == item["offer_id"])
            .values(
                ozon_product_id=item["id"],
                stage="published" if item["visible"] else "archived"
            )
        )
        updated += result.rowcount
    
    await db.commit()
    
    return {
        "synced": len(details),
        "updated": updated
    }
```

### 前端（待实现）

```tsx
// studio/src/pages/products/SyncButton.tsx

import { Button, message } from 'antd';
import { SyncOutlined } from '@ant-design/icons';

export function SyncFromOzonButton({ shopId }) {
  const [syncing, setSyncing] = useState(false);
  
  const handleSync = async () => {
    setSyncing(true);
    try {
      const resp = await fetch(
        `/api/products/sync-from-ozon?shop_id=${shopId}`
      );
      const data = await resp.json();
      
      message.success(
        `已同步 ${data.synced} 个商品，更新 ${data.updated} 条记录`
      );
    } catch (err) {
      message.error(`同步失败: ${err.message}`);
    } finally {
      setSyncing(false);
    }
  };
  
  return (
    <Button
      icon={<SyncOutlined />}
      loading={syncing}
      onClick={handleSync}
    >
      从 Ozon 同步
    </Button>
  );
}
```

---

## 10. 高级用法

### 增量同步

```python
async def incremental_sync(last_sync_time: datetime):
    """增量同步：只拉取最近更新的商品"""
    # Ozon 的 /list 接口不支持按更新时间筛选
    # 策略：全量拉 ID，对比本地 updated_at，只查变化的
    
    ozon_items = await fetch_all_products()
    ozon_ids = {item["product_id"] for item in ozon_items}
    
    # 查本地已有的 product_id
    local = await db.execute(
        select(Product.ozon_product_id, Product.updated_at)
        .where(Product.ozon_product_id.isnot(None))
    )
    local_map = {
        row.ozon_product_id: row.updated_at
        for row in local.fetchall()
    }
    
    # 找出新增的 ID
    new_ids = ozon_ids - set(local_map.keys())
    
    # 批量查详情（只查新增的）
    if new_ids:
        details = await batch_get_product_info(list(new_ids))
        # 插入数据库
        ...
```

---

## 相关文档

- [04-product-import.md](./04-product-import.md) —— 创建/更新商品
- [05-product-info.md](./05-product-info.md) —— 查询商品详情
- [09-stocks.md](./09-stocks.md) —— 库存管理
- [docs/v2/database.md](../v2/database.md) —— products 表结构