daren/brands.md

# Brands 模块 API 文档

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

## 目录

1. [通用说明](#通用说明)
2. [品牌相关接口](#品牌相关接口)
3. [产品相关接口](#产品相关接口)
4. [活动相关接口](#活动相关接口)
5. [WebSocket 接口](#websocket-接口)
6. [状态轮询管理](#状态轮询管理)

## 通用说明

### 基础URL

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

### 认证方式

除特殊说明外，所有 API 都需要 Token 认证。请在请求头中添加：

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

### 响应格式

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

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

## 品牌相关接口

### 获取品牌列表

- **URL**: `/brands/`
- **方法**: GET
- **描述**: 获取所有品牌的列表
- **参数**: 无
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid-string",
        "name": "品牌名称",
        "description": "品牌描述",
        "logo_url": "品牌Logo链接",
        "category": "品牌分类",
        "source": "来源",
        "collab_count": 10,
        "creators_count": 20,
        "campaign_id": "活动ID",
        "total_gmv_achieved": "1000.00",
        "total_views_achieved": "5000.00",
        "shop_overall_rating": "4.5",
        "dataset_id_list": ["id1", "id2"],
        "created_at": "2023-01-01T00:00:00Z",
        "updated_at": "2023-01-01T00:00:00Z",
        "is_active": true
      }
    ]
  }
  ```

### 获取单个品牌详情

- **URL**: `/brands/{brand_id}/`
- **方法**: GET
- **描述**: 获取指定ID的品牌详细信息
- **参数**:
  - `brand_id`: 品牌ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "id": "uuid-string",
      "name": "品牌名称",
      "description": "品牌描述",
      "logo_url": "品牌Logo链接",
      "category": "品牌分类",
      "source": "来源",
      "collab_count": 10,
      "creators_count": 20,
      "campaign_id": "活动ID",
      "total_gmv_achieved": "1000.00",
      "total_views_achieved": "5000.00",
      "shop_overall_rating": "4.5",
      "dataset_id_list": ["id1", "id2"],
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z",
      "is_active": true,
      "products": [...],  // 品牌关联的产品列表
      "campaigns": [...]  // 品牌关联的活动列表
    }
  }
  ```

### 创建品牌

- **URL**: `/brands/`
- **方法**: POST
- **描述**: 创建新的品牌
- **请求参数**:
  ```json
  {
    "name": "品牌名称",  // 必填
    "description": "品牌描述",
    "logo_url": "品牌Logo链接",
    "category": "品牌分类",
    "source": "来源"
  }
  ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "id": "uuid-string",
      "name": "品牌名称",
      "description": "品牌描述",
      // ... 其他字段
    }
  }
  ```

### 更新品牌

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

### 删除品牌

- **URL**: `/brands/{brand_id}/`
- **方法**: DELETE
- **描述**: 删除品牌（软删除）
- **参数**:
  - `brand_id`: 品牌ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "删除成功",
    "data": null
  }
  ```

### 获取品牌产品列表

- **URL**: `/brands/{brand_id}/products/`
- **方法**: GET
- **描述**: 获取指定品牌下的所有产品
- **参数**:
  - `brand_id`: 品牌ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      // 产品列表
    ]
  }
  ```

### 获取品牌活动列表

- **URL**: `/brands/{brand_id}/campaigns/`
- **方法**: GET
- **描述**: 获取指定品牌下的所有活动
- **参数**:
  - `brand_id`: 品牌ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      // 活动列表
    ]
  }
  ```

### 获取品牌知识库ID列表

- **URL**: `/brands/{brand_id}/dataset_ids/`
- **方法**: GET
- **描述**: 获取指定品牌的所有知识库ID
- **参数**:
  - `brand_id`: 品牌ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "dataset_id_list": ["id1", "id2", "id3"]
    }
  }
  ```

## 产品相关接口

### 获取产品列表

- **URL**: `/products/`
- **方法**: GET
- **描述**: 获取所有产品列表
- **参数**: 无
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid-string",
        "brand": "品牌ID",
        "name": "产品名称",
        "description": "产品描述",
        "image_url": "产品图片",
        "pid": "产品ID",
        "commission_rate": "10.00",
        "open_collab": "5.00",
        "available_samples": 10,
        "sales_price_min": "50.00",
        "sales_price_max": "100.00",
        "stock": 100,
        "items_sold": 50,
        "product_rating": "4.5",
        "reviews_count": 20,
        "collab_creators": 5,
        "tiktok_shop": false,
        "dataset_id": "知识库ID",
        "external_id": "外部ID",
        "created_at": "2023-01-01T00:00:00Z",
        "updated_at": "2023-01-01T00:00:00Z",
        "is_active": true
      }
    ]
  }
  ```

### 获取单个产品详情

- **URL**: `/products/{product_id}/`
- **方法**: GET
- **描述**: 获取指定ID的产品详情
- **参数**:
  - `product_id`: 产品ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      // 产品详情
    }
  }
  ```

### 创建产品

- **URL**: `/products/`
- **方法**: POST
- **描述**: 创建新的产品
- **请求参数**:
  ```json
  {
    "brand": "品牌ID",  // 必填
    "name": "产品名称",  // 必填
    "description": "产品描述",
    "image_url": "产品图片",
    "pid": "产品ID",
    "commission_rate": 10.00,
    "dataset_id": "知识库ID"  // 必填
    // ... 其他字段
  }
  ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      // 创建的产品信息
    }
  }
  ```

### 更新产品

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

### 删除产品

- **URL**: `/products/{product_id}/`
- **方法**: DELETE
- **描述**: 删除产品（软删除）
- **参数**:
  - `product_id`: 产品ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "删除成功",
    "data": null
  }
  ```

## 活动相关接口

### 获取活动列表

- **URL**: `/campaigns/`
- **方法**: GET
- **描述**: 获取所有活动列表
- **参数**: 无
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "活动ID",
        "brand": "品牌ID",
        "name": "活动名称",
        "description": "活动描述",
        "image_url": "活动图片",
        "service": "服务类型",
        "creator_type": "创作者类型",
        "creator_level": "创作者等级",
        "creator_category": "创作者分类",
        "creators_count": 10,
        "gmv": "GMV范围",
        "followers": "粉丝数范围",
        "views": "浏览量范围",
        "budget": "预算范围",
        "link_product": ["产品ID1", "产品ID2"],
        "start_date": "2023-01-01T00:00:00Z",
        "end_date": "2023-02-01T00:00:00Z",
        "dataset_id": "知识库ID",
        "external_id": "外部ID",
        "status": "待处理", // pending, accepted, rejected, completed, in_progress
        "gmv_achieved": "实现GMV",
        "views_achieved": "实现观看量",
        "video_link": "视频链接",
        "created_at": "2023-01-01T00:00:00Z",
        "updated_at": "2023-01-01T00:00:00Z",
        "is_active": true
      }
    ]
  }
  ```

### 获取单个活动详情

- **URL**: `/campaigns/{campaign_id}/`
- **方法**: GET
- **描述**: 获取指定ID的活动详情
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      // 活动详情
    }
  }
  ```

### 创建活动

- **URL**: `/campaigns/`
- **方法**: POST
- **描述**: 创建新的活动
- **请求参数**:
  ```json
  {
    "brand": "品牌ID",  // 必填
    "name": "活动名称",  // 必填
    "description": "活动描述",
    "image_url": "活动图片",
    "service": "服务类型",
    "creator_type": "创作者类型",
    "dataset_id": "知识库ID",  // 必填
    // ... 其他字段
  }
  ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      // 创建的活动信息
    }
  }
  ```

### 更新活动

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

### 删除活动

- **URL**: `/campaigns/{campaign_id}/`
- **方法**: DELETE
- **描述**: 删除活动（软删除）
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "删除成功",
    "data": null
  }
  ```

### 向活动添加产品

- **URL**: `/campaigns/{campaign_id}/add_product/`
- **方法**: POST
- **描述**: 将产品添加到活动中
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
  - 请求体:
    ```json
    {
      "product_id": "产品ID"
    }
    ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "产品添加成功",
    "data": null
  }
  ```

### 从活动移除产品

- **URL**: `/campaigns/{campaign_id}/remove_product/`
- **方法**: POST
- **描述**: 从活动中移除产品
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
  - 请求体:
    ```json
    {
      "product_id": "产品ID"
    }
    ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "产品移除成功",
    "data": null
  }
  ```

### 获取活动创作者列表

- **URL**: `/campaigns/{campaign_id}/creator_list/`
- **方法**: GET
- **描述**: 获取指定活动的创作者列表
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "campaign": {
        "id": "活动ID",
        "name": "活动名称",
        "description": "活动描述",
        "image_url": "活动图片",
        "service": "服务类型",
        "creator_type": "创作者类型",
        "creator_level": "创作者等级",
        "creator_category": "创作者分类",
        "creators_count": 10,
        "gmv": "GMV范围",
        "followers": "粉丝数范围",
        "views": "浏览量范围",
        "budget": "预算范围",
        "start_date": "2023-01-01T00:00:00Z",
        "end_date": "2023-02-01T00:00:00Z",
        "status": "状态"
      },
      "creators": [
        {
          "id": "创作者ID",
          "name": "创作者名称",
          "category": "创作者分类",
          "followers": 5000,
          "gmv_generated": "1000.00",
          "views_generated": "5000",
          "pricing": "100.00",
          "status": "状态"
        }
      ]
    }
  }
  ```

### 获取WebSocket连接URL

- **URL**: `/campaigns/{campaign_id}/websocket_url/`
- **方法**: GET
- **描述**: 获取带有认证Token的WebSocket连接URL
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
  - 查询参数:
    - `product_id`: 可选，用于获取特定产品的WebSocket连接
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "websocket_url": "ws://127.0.0.1:8000/ws/campaigns/12345/status/?token=abc123"
    }
  }
  ```

### 获取当前Token信息

- **URL**: `/campaigns/token_info/`
- **方法**: GET
- **描述**: 获取当前用户的认证Token信息和WebSocket连接示例
- **参数**: 无
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "user_id": "用户ID",
      "email": "用户邮箱",
      "token": "认证Token",
      "expires_at": "过期时间",
      "websocket_example": {
        "campaign": "ws://127.0.0.1:8000/ws/campaigns/campaign_id/status/?token=abc123",
        "product": "ws://127.0.0.1:8000/ws/campaigns/campaign_id/status/?product_id=product_id&token=abc123"
      }
    }
  }
  ```

## WebSocket 接口

### 建立活动状态WebSocket连接

- **URL**: `ws://127.0.0.1:8000/ws/campaigns/{campaign_id}/status/?token={token}`
- **描述**: 建立WebSocket连接，获取活动状态的实时更新
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
  - 查询参数:
    - `token`: 用户认证Token (必填)
    - `product_id`: 可选，用于获取特定产品的状态
- **连接成功后接收的数据格式**:
  ```json
  {
    "campaign": {
      // 活动信息
    },
    "creators": [
      // 创作者列表
    ]
  }
  ```

### WebSocket连接JavaScript示例

```javascript
// 获取WebSocket URL
const response = await fetch(`http://127.0.0.1:8000/api/campaigns/${campaignId}/websocket_url/`);
const data = await response.json();
const wsUrl = data.data.websocket_url;

// 建立WebSocket连接
const socket = new WebSocket(wsUrl);

// 连接打开事件
socket.onopen = function(e) {
  console.log("WebSocket连接已建立");
};

// 接收消息事件
socket.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log("接收到的数据:", data);
  // 处理接收到的数据
};

// 错误事件
socket.onerror = function(error) {
  console.error("WebSocket错误:", error);
};

// 连接关闭事件
socket.onclose = function(event) {
  console.log("WebSocket连接已关闭");
};
```

## 状态轮询管理

### 停止轮询

- **URL**: `/campaigns/{campaign_id}/stop_polling/`
- **方法**: POST
- **描述**: 停止指定活动的状态轮询
- **参数**:
  - `campaign_id`: 活动ID (路径参数)
  - 请求体:
    ```json
    {
      "product_id": "产品ID"  // 可选，不提供则停止整个活动的轮询
    }
    ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "轮询已停止",
    "data": null
  }
  ```

### 获取活跃轮询任务

- **URL**: `/campaigns/active_polling_tasks/`
- **方法**: GET
- **描述**: 获取当前系统中所有活跃的轮询任务
- **参数**: 无
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "active_tasks": [
        {
          "campaign_id": "活动ID",
          "product_id": "产品ID",  // 如果存在
          "interval": 30,  // 轮询间隔，单位为秒
          "last_poll": "2023-01-01T00:00:00Z"
        }
      ]
    }
  }
  ```