daren/apps/discovery/discovery.md

# Discovery模块API文档

## 概述

Discovery (发现) 模块是一个用于搜索和发现创作者/达人的系统。该模块提供了一系列RESTful API接口，用于创建搜索会话、搜索创作者和查询历史搜索结果。

## 通用响应格式

所有API响应都遵循以下统一的JSON格式：

```json
{
  "code": 200,      // 状态码，200表示成功，其他值表示错误
  "message": "成功", // 响应消息
  "data": {}        // 响应数据，可能是对象、数组或null
}
```

## 分页响应格式

使用分页的接口将返回以下格式：

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

## 认证方式

所有接口都需要使用自定义Token认证，请在HTTP请求头中添加以下字段：

```
Authorization: Token your_token_here
```

## 1. 搜索会话管理 (Sessions)

搜索会话保存了搜索历史记录和搜索结果，便于追踪和回顾之前的搜索。

### 1.1 获取搜索会话列表

- **URL**: `/sessions/`
- **方法**: `GET`
- **描述**: 获取所有搜索会话的列表
- **请求参数**:
  - `page`: 页码，默认为1
  - `page_size`: 每页记录数，默认为20，最大为100
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取搜索会话列表成功",
    "data": {
      "count": 10,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 1,
          "session_number": 1,
          "creator_count": 20,
          "shoppable_creators": 15,
          "avg_followers": 10000.5,
          "avg_gmv": 5000.25,
          "avg_video_views": 20000.75,
          "date_created": "2023-06-01"
        }
      ]
    }
  }
  ```

### 1.2 创建搜索会话

- **URL**: `/sessions/`
- **方法**: `POST`
- **描述**: 创建一个新的搜索会话
- **请求参数**:
  ```json
  {
    "session_number": 1,             // 可选，默认为1
    "creator_count": 0,              // 可选，默认为0
    "shoppable_creators": 0,         // 可选，默认为0
    "avg_followers": 0,              // 可选，默认为0
    "avg_gmv": 0,                    // 可选，默认为0
    "avg_video_views": 0,            // 可选，默认为0
    "date_created": "2023-06-01"     // 可选，默认为当前日期
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "创建搜索会话成功",
    "data": {
      "id": 1,
      "session_number": 1,
      "creator_count": 0,
      "shoppable_creators": 0,
      "avg_followers": 0,
      "avg_gmv": 0,
      "avg_video_views": 0,
      "date_created": "2023-06-01"
    }
  }
  ```

### 1.3 获取搜索会话详情

- **URL**: `/sessions/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的搜索会话详情，包含相关的创作者数据
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取搜索会话详情成功",
    "data": {
      "id": 1,
      "session_number": 1,
      "creator_count": 20,
      "shoppable_creators": 15,
      "avg_followers": 10000.5,
      "avg_gmv": 5000.25,
      "avg_video_views": 20000.75,
      "date_created": "2023-06-01",
      "creators": [
        {
          "id": 1,
          "session": 1,
          "name": "创作者名称",
          "avatar": "https://example.com/avatar.jpg",
          "category": "Sports & Outdoor",
          "ecommerce_level": "L3",
          "exposure_level": "KOL-2",
          "followers": 15000,
          "gmv": 8000,
          "items_sold": 500,
          "avg_video_views": 25000,
          "has_ecommerce": true,
          "tiktok_url": "https://tiktok.com/@username",
          "hashtags": "#sport#fitness#outdoor",
          "trends": "summer fitness",
          "profile": "tiktok"
        }
      ]
    }
  }
  ```

### 1.4 更新搜索会话

- **URL**: `/sessions/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的搜索会话信息
- **请求参数**: 同创建搜索会话
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "更新搜索会话成功",
    "data": {
      "id": 1,
      "session_number": 2,
      "creator_count": 25,
      "shoppable_creators": 18,
      "avg_followers": 12000.5,
      "avg_gmv": 6000.25,
      "avg_video_views": 22000.75,
      "date_created": "2023-06-01"
    }
  }
  ```

### 1.5 删除搜索会话

- **URL**: `/sessions/{id}/`
- **方法**: `DELETE`
- **描述**: 删除指定ID的搜索会话
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "删除搜索会话成功",
    "data": null
  }
  ```

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

- **URL**: `/sessions/{id}/results/`
- **方法**: `GET`
- **描述**: 获取指定会话的搜索结果（创作者列表）
- **请求参数**:
  - `page`: 页码，默认为1
  - `page_size`: 每页记录数，默认为20，最大为100
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取会话创作者列表成功",
    "data": {
      "count": 20,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 1,
          "session": 1,
          "name": "创作者名称",
          "avatar": "https://example.com/avatar.jpg",
          "category": "Sports & Outdoor",
          "ecommerce_level": "L3",
          "exposure_level": "KOL-2",
          "followers": 15000,
          "gmv": 8000,
          "items_sold": 500,
          "avg_video_views": 25000,
          "has_ecommerce": true,
          "tiktok_url": "https://tiktok.com/@username",
          "hashtags": "#sport#fitness#outdoor",
          "trends": "summer fitness",
          "profile": "tiktok"
        }
      ]
    }
  }
  ```

### 1.7 获取会话摘要

- **URL**: `/sessions/summary/`
- **方法**: `GET`
- **描述**: 获取所有会话的摘要数据，用于展示在表格中
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取会话摘要列表成功",
    "data": [
      {
        "id": 1,
        "session_number": 1,
        "date": "2023-06-01",
        "creator_count": 20,
        "shoppable_creators": 15,
        "avg_followers": 10000.5,
        "avg_gmv": 5000.25,
        "avg_video_views": 20000.75
      }
    ]
  }
  ```

## 2. 创作者管理 (Creators)

创作者是系统中的核心数据实体，代表平台上的内容创作者/达人。

### 2.1 获取创作者列表

- **URL**: `/creators/`
- **方法**: `GET`
- **描述**: 获取所有创作者的列表
- **请求参数**:
  - `page`: 页码，默认为1
  - `page_size`: 每页记录数，默认为20，最大为100
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取创作者列表成功",
    "data": {
      "count": 100,
      "next": "http://example.com/api/creators/?page=2",
      "previous": null,
      "results": [
        {
          "id": 1,
          "session": 1,
          "name": "创作者名称",
          "avatar": "https://example.com/avatar.jpg",
          "category": "Sports & Outdoor",
          "ecommerce_level": "L3",
          "exposure_level": "KOL-2",
          "followers": 15000,
          "gmv": 8000,
          "items_sold": 500,
          "avg_video_views": 25000,
          "has_ecommerce": true,
          "tiktok_url": "https://tiktok.com/@username",
          "hashtags": "#sport#fitness#outdoor",
          "trends": "summer fitness",
          "profile": "tiktok"
        }
      ]
    }
  }
  ```

### 2.2 获取创作者详情

- **URL**: `/creators/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的创作者详细信息
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取创作者详情成功",
    "data": {
      "id": 1,
      "session": 1,
      "name": "创作者名称",
      "avatar": "https://example.com/avatar.jpg",
      "category": "Sports & Outdoor",
      "ecommerce_level": "L3",
      "exposure_level": "KOL-2",
      "followers": 15000,
      "gmv": 8000,
      "items_sold": 500,
      "avg_video_views": 25000,
      "has_ecommerce": true,
      "tiktok_url": "https://tiktok.com/@username",
      "hashtags": "#sport#fitness#outdoor",
      "trends": "summer fitness",
      "profile": "tiktok"
    }
  }
  ```

### 2.3 搜索创作者

- **URL**: `/creators/search/`
- **方法**: `POST`
- **描述**: 根据多种条件搜索创作者，会自动创建搜索会话并保存搜索结果
- **请求参数**:
  ```json
  {
    "query": "运动",              // 可选，搜索关键词
    "category": "Sports & Outdoor", // 可选，类别
    "ecommerce_level": "L3",        // 可选，电商等级（L1-L5）
    "exposure_level": "KOL-2",      // 可选，曝光等级
    "hashtag": "fitness",           // 可选，标签
    "trend": "summer",              // 可选，趋势
    "profile": "tiktok"             // 可选，平台（tiktok、instagram等）
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "搜索创作者成功",
    "data": {
      "id": 1,
      "session_number": 1,
      "creator_count": 5,
      "shoppable_creators": 3,
      "avg_followers": 12000.5,
      "avg_gmv": 5500.25,
      "avg_video_views": 20500.75,
      "date_created": "2023-06-01",
      "creators": [
        {
          "id": 1,
          "session": 1,
          "name": "创作者名称",
          "avatar": "https://example.com/avatar.jpg",
          "category": "Sports & Outdoor",
          "ecommerce_level": "L3",
          "exposure_level": "KOL-2",
          "followers": 15000,
          "gmv": 8000,
          "items_sold": 500,
          "avg_video_views": 25000,
          "has_ecommerce": true,
          "tiktok_url": "https://tiktok.com/@username",
          "hashtags": "#sport#fitness#outdoor",
          "trends": "summer fitness",
          "profile": "tiktok"
        }
      ]
    }
  }
  ```

### 2.4 搜索标签和趋势

- **URL**: `/creators/search_tags/`
- **方法**: `POST`
- **描述**: 专门用于搜索标签和趋势，会创建搜索会话并保存搜索结果
- **请求参数**:
  ```json
  {
    "mode": "hashtag",        // 必填，搜索模式，"hashtag"或"trend"
    "keyword": "fitness",     // 必填，搜索关键词
    "profile": "tiktok"       // 可选，平台
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "搜索hashtag成功，关键词: fitness",
    "data": {
      "id": 1,
      "session_number": 1,
      "creator_count": 8,
      "shoppable_creators": 5,
      "avg_followers": 13000.5,
      "avg_gmv": 6500.25,
      "avg_video_views": 22500.75,
      "date_created": "2023-06-01",
      "creators": [
        {
          "id": 1,
          "session": 1,
          "name": "创作者名称",
          "avatar": "https://example.com/avatar.jpg",
          "category": "Sports & Outdoor",
          "ecommerce_level": "L3",
          "exposure_level": "KOL-2",
          "followers": 15000,
          "gmv": 8000,
          "items_sold": 500,
          "avg_video_views": 25000,
          "has_ecommerce": true,
          "tiktok_url": "https://tiktok.com/@username",
          "hashtags": "#sport#fitness#outdoor",
          "trends": "summer fitness",
          "profile": "tiktok"
        }
      ]
    }
  }
  ```

### 2.5 自然语言搜索创作者

- **URL**: `/creators/search_individual/`
- **方法**: `POST`
- **描述**: 根据用户输入的自然语言文本搜索达人，使用外部API进行处理
- **请求参数**:
  ```json
  {
    "criteria": "我需要粉丝超过10万的健身类达人，擅长做运动装备测评", // 必填，搜索条件
    "top_n": 10                                         // 可选，返回结果数量，默认10
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "搜索创作者成功",
    "data": {
      "id": 1,
      "session_number": 1,
      "creator_count": 10,
      "shoppable_creators": 7,
      "avg_followers": 150000.5,
      "avg_gmv": 9500.25,
      "avg_video_views": 35000.75,
      "date_created": "2023-06-01",
      "creators": [
        {
          "id": 1,
          "session": 1,
          "name": "创作者名称",
          "avatar": "https://example.com/avatar.jpg",
          "category": "Sports & Outdoor",
          "ecommerce_level": "L4",
          "exposure_level": "KOL-2",
          "followers": 180000,
          "gmv": 12000,
          "items_sold": 800,
          "avg_video_views": 45000,
          "has_ecommerce": true,
          "tiktok_url": "https://tiktok.com/@username",
          "hashtags": "#sport#fitness#outdoor#review",
          "trends": "fitness equipment review",
          "profile": "tiktok"
        }
      ]
    }
  }
  ```

## 3. 字段说明

### 3.1 搜索会话字段

| 字段名             | 类型    | 说明                         |
|------------------|---------|------------------------------|
| id               | 整数    | 会话ID                       |
| session_number   | 整数    | 会话编号                      |
| creator_count    | 整数    | 创作者数量                    |
| shoppable_creators | 整数  | 可购物创作者数量              |
| avg_followers    | 浮点数  | 平均粉丝数                    |
| avg_gmv          | 浮点数  | 平均GMV(商品总价值)           |
| avg_video_views  | 浮点数  | 平均视频观看量                |
| date_created     | 日期    | 创建日期                      |

### 3.2 创作者字段

| 字段名             | 类型    | 说明                         |
|------------------|---------|------------------------------|
| id               | 整数    | 创作者ID                     |
| session          | 整数    | 所属会话ID                    |
| name             | 字符串  | 创作者名称                    |
| avatar           | URL     | 头像链接                      |
| category         | 字符串  | 类别，可选值：Phones & Electronics, Womenswear & Underwear等 |
| ecommerce_level  | 字符串  | 电商等级，可选值：L1, L2, L3, L4, L5, New tag |
| exposure_level   | 字符串  | 曝光等级，可选值：KOC-1, KOC-2, KOL-2, KOL-3, New tag |
| followers        | 浮点数  | 粉丝数                        |
| gmv              | 浮点数  | GMV(商品总价值)               |
| items_sold       | 浮点数  | 已售项目数                    |
| avg_video_views  | 浮点数  | 平均视频观看量                |
| has_ecommerce    | 布尔值  | 是否有电商                    |
| tiktok_url       | URL     | 抖音链接                      |
| hashtags         | 字符串  | 标签，格式如"#sport#fitness"   |
| trends           | 字符串  | 趋势，格式如"summer fitness"   |
| profile          | 字符串  | 达人平台，可选值：tiktok, instagram, youtube, xiaohongshu, other |

## 4. 使用示例

### 4.1 搜索标签为"fitness"的TikTok创作者

```http
POST /api/creators/search_tags/
Content-Type: application/json
Authorization: Token your_token_here

{
  "mode": "hashtag",
  "keyword": "fitness",
  "profile": "tiktok"
}
```

### 4.2 获取最近一次搜索会话的详情

```http
GET /api/sessions/1/
Authorization: Token your_token_here
```

### 4.3 使用自然语言搜索创作者

```http
POST /api/creators/search_individual/
Content-Type: application/json
Authorization: Token your_token_here

{
  "criteria": "需要3个粉丝超过50万的美妆达人，产品转化率高",
  "top_n": 3
}
```