daren/discovery.md

# Discovery 模块 API 文档

本文档详细说明了 Discovery 模块的 API 接口，包括请求方法、URL、参数说明和响应格式。

## 目录

1. [通用说明](#通用说明)
2. [创作者搜索会话接口](#创作者搜索会话接口)
3. [创作者发现接口](#创作者发现接口)

## 通用说明

### 基础URL

所有 API 的基础 URL 为：`http://127.0.0.1:8000/api/discovery/`

### 认证方式

所有 API 都需要 Token 认证。请在请求头中添加：

```
Authorization: Token <your_token>
```

### 响应格式

所有 API 返回的数据格式统一为：

```json
{
  "code": 200,        // 状态码，200表示成功，其他表示错误
  "message": "成功",   // 状态描述
  "data": {}          // 返回的数据，可能是对象、数组或null
}
```

### 分页

列表接口支持分页，默认每页 20 条数据，最大每页 100 条。

分页参数：
- `page`: 页码，从1开始
- `page_size`: 每页数量，默认20

分页响应格式：

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 100,             // 总记录数
    "next": "下一页URL",       // 下一页链接，如果没有则为null
    "previous": "上一页URL",   // 上一页链接，如果没有则为null
    "results": []             // 当前页数据
  }
}
```

## 创作者搜索会话接口

搜索会话是指用户进行的一次创作者搜索，包含搜索结果和相关统计信息。

### 获取搜索会话列表

- **URL**: `/sessions/`
- **方法**: GET
- **描述**: 获取所有搜索会话的列表
- **参数**: 
  - 分页参数，参见[分页](#分页)部分
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "获取搜索会话列表成功",
    "data": [
      {
        "id": 1,
        "session_number": 123,
        "creator_count": 100,
        "shoppable_creators": 26,
        "avg_followers": 162.2,
        "avg_gmv": 534.1,
        "avg_video_views": 1.9,
        "date_created": "2023-01-01"
      }
    ]
  }
  ```

### 获取搜索会话详情

- **URL**: `/sessions/{session_id}/`
- **方法**: GET
- **描述**: 获取指定ID的搜索会话详细信息，包含搜索到的创作者列表
- **参数**:
  - `session_id`: 会话ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "获取搜索会话详情成功",
    "data": {
      "id": 1,
      "session_number": 123,
      "creator_count": 100,
      "shoppable_creators": 26,
      "avg_followers": 162.2,
      "avg_gmv": 534.1,
      "avg_video_views": 1.9,
      "date_created": "2023-01-01",
      "creators": [
        // 创作者列表，见创作者数据结构
      ]
    }
  }
  ```

### 创建搜索会话

- **URL**: `/sessions/`
- **方法**: POST
- **描述**: 创建新的搜索会话
- **请求参数**:
  ```json
  {
    "session_number": 123,
    "creator_count": 100,
    "shoppable_creators": 26,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2023-01-01"
  }
  ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "创建搜索会话成功",
    "data": {
      "id": 1,
      "session_number": 123,
      "creator_count": 100,
      "shoppable_creators": 26,
      "avg_followers": 162.2,
      "avg_gmv": 534.1,
      "avg_video_views": 1.9,
      "date_created": "2023-01-01"
    }
  }
  ```

### 更新搜索会话

- **URL**: `/sessions/{session_id}/`
- **方法**: PUT/PATCH
- **描述**: 更新搜索会话信息
- **参数**:
  - `session_id`: 会话ID (路径参数)
  - 请求体包含要更新的字段
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "更新搜索会话成功",
    "data": {
      // 更新后的会话信息
    }
  }
  ```

### 删除搜索会话

- **URL**: `/sessions/{session_id}/`
- **方法**: DELETE
- **描述**: 删除搜索会话
- **参数**:
  - `session_id`: 会话ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "删除搜索会话成功",
    "data": null
  }
  ```

### 获取会话创作者列表

- **URL**: `/sessions/{session_id}/results/`
- **方法**: GET
- **描述**: 获取指定会话的搜索结果（创作者列表）
- **参数**:
  - `session_id`: 会话ID (路径参数)
  - 分页参数，参见[分页](#分页)部分
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "获取会话创作者列表成功",
    "data": [
      // 创作者列表，见创作者数据结构
    ]
  }
  ```

## 创作者发现接口

### 获取创作者列表

- **URL**: `/creators/`
- **方法**: GET
- **描述**: 获取所有创作者的列表
- **参数**: 
  - 分页参数，参见[分页](#分页)部分
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "获取创作者列表成功",
    "data": [
      {
        "id": 1,
        "name": "创作者名称",
        "avatar": "头像URL",
        "category": "Phones & Electronics",
        "ecommerce_level": "L2",
        "exposure_level": "KOC-1",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": true,
        "tiktok_url": "抖音链接",
        "session": 1
      }
    ]
  }
  ```

### 获取创作者详情

- **URL**: `/creators/{creator_id}/`
- **方法**: GET
- **描述**: 获取指定ID的创作者详细信息
- **参数**:
  - `creator_id`: 创作者ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "获取创作者详情成功",
    "data": {
      "id": 1,
      "name": "创作者名称",
      "avatar": "头像URL",
      "category": "Phones & Electronics",
      "ecommerce_level": "L2",
      "exposure_level": "KOC-1",
      "followers": 162.2,
      "gmv": 534.1,
      "items_sold": 18.1,
      "avg_video_views": 1.9,
      "has_ecommerce": true,
      "tiktok_url": "抖音链接",
      "session": 1
    }
  }
  ```

### 搜索创作者

- **URL**: `/creators/search/`
- **方法**: POST
- **描述**: 根据条件搜索创作者并创建新的搜索会话
- **请求参数**:
  ```json
  {
    "query": "搜索关键词",
    "category": "Phones & Electronics",  // 可选，见类别列表
    "ecommerce_level": "L2",            // 可选，见电商等级列表
    "exposure_level": "KOC-1"           // 可选，见曝光等级列表
  }
  ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "搜索创作者成功",
    "data": {
      "id": 1,
      "session_number": 123,
      "creator_count": 5,
      "shoppable_creators": 3,
      "avg_followers": 162.2,
      "avg_gmv": 534.1,
      "avg_video_views": 1.9,
      "date_created": "2023-01-01",
      "creators": [
        // 创作者列表，见创作者数据结构
      ]
    }
  }
  ```

## 数据结构

### 创作者类别

- `Phones & Electronics`: 手机与电子产品
- `Womenswear & Underwear`: 女装与内衣
- `Sports & Outdoor`: 运动与户外
- `Food & Beverage`: 食品与饮料
- `Health`: 健康
- `Kitchenware`: 厨具
- `Furniture`: 家具
- `Shoes`: 鞋类
- `Home Supplies`: 家居用品

### 电商等级

- `L1`: Level 1
- `L2`: Level 2
- `L3`: Level 3
- `L4`: Level 4
- `L5`: Level 5
- `New tag`: 新标签

### 曝光等级

- `KOC-1`: Key Opinion Consumer 1级
- `KOC-2`: Key Opinion Consumer 2级
- `KOL-2`: Key Opinion Leader 2级
- `KOL-3`: Key Opinion Leader 3级
- `New tag`: 新标签

### 创作者数据结构

```json
{
  "id": 1,
  "name": "创作者名称",
  "avatar": "头像URL",
  "category": "Phones & Electronics",
  "ecommerce_level": "L2",
  "exposure_level": "KOC-1",
  "followers": 162.2,       // 单位：K (千)
  "gmv": 534.1,             // 单位：K (千)
  "items_sold": 18.1,        // 单位：K (千)
  "avg_video_views": 1.9,    // 单位：M (百万)
  "has_ecommerce": true,     // 是否有电商能力
  "tiktok_url": "抖音链接",
  "session": 1               // 所属搜索会话ID
}
```

### 搜索会话数据结构

```json
{
  "id": 1,
  "session_number": 123,      // 会话编号
  "creator_count": 100,       // 创作者数量
  "shoppable_creators": 26,   // 可购物创作者数量
  "avg_followers": 162.2,     // 平均粉丝数 (K)
  "avg_gmv": 534.1,           // 平均GMV (K)
  "avg_video_views": 1.9,     // 平均视频观看量 (M)
  "date_created": "2023-01-01" // 创建日期
}
```