operations_project/apps/discovery/README.md

# Discovery API 接口文档

## 简介

Discovery API是一个用于发现和搜索创作者的接口。它提供了创作者搜索、搜索会话管理等功能。所有API响应均遵循统一格式：

```json
{
  "code": 200,  // 状态码，200表示成功
  "message": "操作成功",  // 操作提示消息
  "data": {  // 实际数据
    // 具体内容
  }
}
```

## 使用Apifox测试接口

1. 下载并安装Apifox: https://www.apifox.cn/
2. 创建新项目，命名为"Creator Discovery"
3. 导入API或手动创建以下接口

## API 接口列表

### 1. 搜索创作者

- **URL**: `http://localhost:8000/api/discovery/creators/search/`
- **方法**: POST
- **描述**: 根据条件搜索创作者，并创建新的搜索会话
- **请求参数**:

```json
{
  "query": "创作者",
  "category": "Health",
  "ecommerce_level": "L5",
  "exposure_level": "KOL-2"
}
```

- **响应示例**:

```json
{
  "code": 200,
  "message": "搜索创作者成功",
  "data": {
    "id": 4,
    "creators": [
      {
        "id": 37,
        "name": "Mock Creator 5",
        "avatar": null,
        "category": "Health",
        "ecommerce_level": "L5",
        "exposure_level": "KOL-2",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": false,
        "tiktok_url": null,
        "session": 4
      }
    ],
    "session_number": 4,
    "creator_count": 1,
    "shoppable_creators": 0,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2023-10-02"
  }
}
```

### 2. 获取搜索会话列表

- **URL**: `http://localhost:8000/api/discovery/sessions/`
- **方法**: GET
- **描述**: 获取所有搜索会话的历史记录
- **查询参数**: 
  - `page`: 页码，默认为1
  - `page_size`: 每页条数，默认为20，最大为100
- **响应示例**:

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 3,
    "next": "http://localhost:8000/api/discovery/sessions/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "session_number": 1,
        "creator_count": 42,
        "shoppable_creators": 24,
        "avg_followers": 162.2,
        "avg_gmv": 534.1,
        "avg_video_views": 1.9,
        "date_created": "2024-01-06"
      },
      {
        "id": 2,
        "session_number": 2,
        "creator_count": 53,
        "shoppable_creators": 13,
        "avg_followers": 162.2,
        "avg_gmv": 534.1,
        "avg_video_views": 1.9,
        "date_created": "2022-01-07"
      }
    ]
  }
}
```

### 3. 获取搜索会话详情

- **URL**: `http://localhost:8000/api/discovery/sessions/{id}/`
- **方法**: GET
- **描述**: 获取特定搜索会话的详细信息，包含该会话中的所有创作者
- **请求参数**: 路径参数 `id`
- **响应示例**:

```json
{
  "code": 200,
  "message": "获取搜索会话详情成功",
  "data": {
    "id": 1,
    "creators": [
      {
        "id": 1,
        "name": "Creator 1 in Session 1",
        "avatar": null,
        "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": null,
        "session": 1
      },
      {
        "id": 2,
        "name": "Creator 9 in Session 1",
        "avatar": null,
        "category": "Womenswear & Underwear",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-3",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": false,
        "tiktok_url": null,
        "session": 1
      }
    ],
    "session_number": 1,
    "creator_count": 42,
    "shoppable_creators": 24,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2024-01-06"
  }
}
```

### 4. 获取会话中的创作者

- **URL**: `http://localhost:8000/api/discovery/sessions/{id}/results/`
- **方法**: GET
- **描述**: 获取特定会话中的所有创作者
- **请求参数**: 
  - 路径参数 `id`
  - 查询参数 `page`、`page_size`（分页参数）
- **响应示例**:

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 42,
    "next": "http://localhost:8000/api/discovery/sessions/1/results/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "name": "Creator 1 in Session 1",
        "avatar": null,
        "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": null,
        "session": 1
      },
      {
        "id": 2,
        "name": "Creator 9 in Session 1",
        "avatar": null,
        "category": "Womenswear & Underwear",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-3",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": false,
        "tiktok_url": null,
        "session": 1
      }
    ]
  }
}
```

### 5. 获取所有创作者

- **URL**: `http://localhost:8000/api/discovery/creators/`
- **方法**: GET
- **描述**: 获取系统中的所有创作者
- **请求参数**: 查询参数 `page`、`page_size`（分页参数）
- **响应示例**:

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 150,
    "next": "http://localhost:8000/api/discovery/creators/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "name": "Creator 1 in Session 1",
        "avatar": null,
        "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": null,
        "session": 1
      },
      // 更多创作者...
    ]
  }
}
```

### 6. 获取创作者详情

- **URL**: `http://localhost:8000/api/discovery/creators/{id}/`
- **方法**: GET
- **描述**: 获取特定创作者的详细信息
- **请求参数**: 路径参数 `id`
- **响应示例**:

```json
{
  "code": 200,
  "message": "获取创作者详情成功",
  "data": {
    "id": 1,
    "name": "Creator 1 in Session 1",
    "avatar": null,
    "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": null,
    "session": 1
  }
}
```

## 在Apifox中设置环境变量

创建一个名为"本地开发环境"的环境，设置以下变量：
- `baseUrl`: `http://localhost:8000/api`

这样可以在所有请求中使用`{{baseUrl}}/discovery/...`来替代完整URL。

## 测试流程示例

1. 启动Django服务器：`python manage.py runserver`
2. 在Apifox中发送请求"获取搜索会话列表"
3. 在响应中选择一个会话ID
4. 使用该ID获取会话详情
5. 使用"搜索创作者"接口创建新的搜索会话
6. 验证新创建的会话是否出现在会话列表中

## 在Apifox中导入API

1. 在Apifox中，点击"导入"按钮
2. 选择"导入API"
3. 将本文档中的API信息整理成集合导入
4. 设置每个接口的请求和响应格式
5. 设置示例响应

## 注意事项

- 所有API响应均遵循统一的格式：`code`、`message`和`data`
- 分页接口返回格式为：`{ "code": 200, "message": "获取数据成功", "data": { "count": 总数, "next": 下一页URL, "previous": 上一页URL, "results": [] } }`
- 即使发生错误，HTTP状态码始终为200，错误信息在响应体的`code`和`message`中提供
- 接口不需要认证，可直接访问