daren/apps/brands/brands.md

# 品牌模块API文档

## 概述

品牌模块是负责管理品牌、产品、活动以及品牌聊天会话的系统。该模块提供了一系列RESTful API接口，用于创建、查询、更新和删除品牌相关的资源。

## 通用响应格式

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

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

## 认证方式

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

```
Authorization: Token your_token_here
```

## 1. 品牌管理 (Brands)

### 1.1 获取品牌列表

- **URL**: `/brands/`
- **方法**: `GET`
- **描述**: 获取所有品牌的列表
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "name": "品牌名称",
        "description": "品牌描述",
        "logo_url": "品牌Logo链接",
        "category": "品牌分类",
        "source": "来源",
        "collab_count": 0,
        "creators_count": 0,
        "campaign_id": "活动ID",
        "total_gmv_achieved": "0.00",
        "total_views_achieved": "0.00",
        "shop_overall_rating": "0.0",
        "dataset_id_list": [],
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

### 1.2 创建品牌

- **URL**: `/brands/`
- **方法**: `POST`
- **描述**: 创建一个新的品牌
- **请求参数**:
  ```json
  {
    "name": "品牌名称",             // 必填，唯一
    "description": "品牌描述",      // 可选
    "logo_url": "品牌Logo链接",     // 可选
    "category": "品牌分类",         // 可选
    "source": "来源",              // 可选
    "collab_count": 0,            // 可选，默认0
    "creators_count": 0,          // 可选，默认0
    "campaign_id": "活动ID",       // 可选
    "total_gmv_achieved": "0.00", // 可选，默认0
    "total_views_achieved": "0.00", // 可选，默认0
    "shop_overall_rating": "0.0", // 可选，默认0
    "is_active": true             // 可选，默认true
  }
  ```
- **响应数据**: 返回创建的品牌信息

### 1.3 获取品牌详情

- **URL**: `/brands/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的品牌详细信息，包括关联的产品和活动
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "id": "uuid字符串",
      "name": "品牌名称",
      "description": "品牌描述",
      "logo_url": "品牌Logo链接",
      "category": "品牌分类",
      "source": "来源",
      "collab_count": 0,
      "creators_count": 0,
      "campaign_id": "活动ID",
      "total_gmv_achieved": "0.00",
      "total_views_achieved": "0.00",
      "shop_overall_rating": "0.0",
      "dataset_id_list": [],
      "products": [],
      "campaigns": [],
      "created_at": "创建时间",
      "updated_at": "更新时间",
      "is_active": true
    }
  }
  ```

### 1.4 更新品牌

- **URL**: `/brands/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的品牌信息
- **请求参数**: 同创建品牌
- **响应数据**: 返回更新后的品牌信息

### 1.5 删除品牌

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

### 1.6 获取品牌产品列表

- **URL**: `/brands/{id}/products/`
- **方法**: `GET`
- **描述**: 获取指定品牌下的所有产品
- **请求参数**: 无
- **响应数据**: 返回产品列表

### 1.7 获取品牌活动列表

- **URL**: `/brands/{id}/campaigns/`
- **方法**: `GET`
- **描述**: 获取指定品牌下的所有活动
- **请求参数**: 无
- **响应数据**: 返回活动列表

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

- **URL**: `/brands/{id}/dataset_ids/`
- **方法**: `GET`
- **描述**: 获取品牌的所有知识库ID
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "dataset_id_list": []
    }
  }
  ```

### 1.8 搜索品牌

- **URL**: `/brands/search/`
- **方法**: `GET`
- **描述**: 根据关键词搜索品牌
- **请求参数**:
  - `keyword`: 搜索关键词（必填）
- **搜索说明**:
  - 搜索范围包括：品牌名称、品牌描述、品牌分类和来源
  - 使用模糊匹配，不区分大小写
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "name": "品牌名称",
        "description": "品牌描述",
        "logo_url": "品牌Logo链接",
        "category": "品牌分类",
        "source": "来源",
        "collab_count": 0,
        "creators_count": 0,
        "campaign_id": "活动ID",
        "total_gmv_achieved": "0.00",
        "total_views_achieved": "0.00",
        "shop_overall_rating": "0.0",
        "dataset_id_list": [],
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

## 2. 产品管理 (Products)

### 2.1 获取产品列表

- **URL**: `/products/`
- **方法**: `GET`
- **描述**: 获取所有产品的列表
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "brand": "品牌ID",
        "brand_name": "品牌名称",
        "name": "产品名称",
        "description": "产品描述",
        "image_url": "产品图片链接",
        "pid": "产品ID",
        "commission_rate": "0.00",
        "open_collab": "0.00",
        "available_samples": 0,
        "sales_price_min": "0.00",
        "sales_price_max": "0.00",
        "stock": 0,
        "items_sold": 0,
        "product_rating": "0.0",
        "reviews_count": 0,
        "collab_creators": 0,
        "tiktok_shop": false,
        "dataset_id": "知识库ID",
        "external_id": "外部ID",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

### 2.2 创建产品

- **URL**: `/products/`
- **方法**: `POST`
- **描述**: 创建一个新的产品，会自动更新关联品牌的dataset_id_list
- **请求参数**:
  ```json
  {
    "brand": "品牌ID",           // 必填
    "name": "产品名称",          // 必填
    "description": "产品描述",   // 可选
    "image_url": "产品图片链接", // 可选
    "pid": "产品ID",            // 可选
    "commission_rate": "0.00",  // 可选
    "open_collab": "0.00",      // 可选
    "available_samples": 0,     // 可选
    "sales_price_min": "0.00",  // 可选
    "sales_price_max": "0.00",  // 可选
    "stock": 0,                 // 可选
    "items_sold": 0,            // 可选
    "product_rating": "0.0",    // 可选
    "reviews_count": 0,         // 可选
    "collab_creators": 0,       // 可选
    "tiktok_shop": false,       // 可选
    "dataset_id": "知识库ID",    // 必填
    "external_id": "外部ID",     // 可选
    "is_active": true           // 可选
  }
  ```
- **响应数据**: 返回创建的产品信息

### 2.3 获取产品详情

- **URL**: `/products/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的产品详细信息
- **请求参数**: 无
- **响应数据**: 返回产品详情

### 2.4 更新产品

- **URL**: `/products/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的产品信息，会自动更新关联品牌的dataset_id_list
- **请求参数**: 同创建产品
- **响应数据**: 返回更新后的产品信息

### 2.5 删除产品

- **URL**: `/products/{id}/`
- **方法**: `DELETE`
- **描述**: 软删除指定ID的产品，并从品牌的dataset_id_list中移除对应的ID
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "删除成功",
    "data": null
  }
  ```

### 2.6 搜索产品

- **URL**: `/products/search/`
- **方法**: `GET`
- **描述**: 根据关键词搜索产品
- **请求参数**:
  - `keyword`: 搜索关键词（必填）
- **搜索说明**:
  - 搜索范围包括：产品名称、产品描述、产品ID和所属品牌名称
  - 使用模糊匹配，不区分大小写
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "brand": "品牌ID",
        "brand_name": "品牌名称",
        "name": "产品名称",
        "description": "产品描述",
        "image_url": "产品图片链接",
        "pid": "产品ID",
        "commission_rate": "0.00",
        "open_collab": "0.00",
        "available_samples": 0,
        "sales_price_min": "0.00",
        "sales_price_max": "0.00",
        "stock": 0,
        "items_sold": 0,
        "product_rating": "0.0",
        "reviews_count": 0,
        "collab_creators": 0,
        "tiktok_shop": false,
        "dataset_id": "知识库ID",
        "external_id": "外部ID",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

## 3. 活动管理 (Campaigns)

### 3.1 获取活动列表

- **URL**: `/campaigns/`
- **方法**: `GET`
- **描述**: 获取所有活动的列表
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "brand": "品牌ID",
        "brand_name": "品牌名称",
        "name": "活动名称",
        "description": "活动描述",
        "image_url": "活动图片链接",
        "service": "服务类型",
        "creator_type": "创作者类型",
        "creator_level": "创作者等级",
        "creator_category": "创作者分类",
        "creators_count": 0,
        "gmv": "GMV范围",
        "followers": "粉丝数范围",
        "views": "浏览量范围",
        "budget": "预算范围",
        "link_product": ["产品ID1", "产品ID2"],
        "link_product_details": [产品详情对象数组],
        "start_date": "开始日期",
        "end_date": "结束日期",
        "dataset_id": "知识库ID",
        "external_id": "外部ID",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

### 3.2 创建活动

- **URL**: `/campaigns/`
- **方法**: `POST`
- **描述**: 创建一个新的活动，会自动更新关联品牌的dataset_id_list
- **请求参数**:
  ```json
  {
    "brand": "品牌ID",               // 必填
    "name": "活动名称",              // 必填
    "description": "活动描述",       // 可选
    "image_url": "活动图片链接",     // 可选
    "service": "服务类型",           // 可选
    "creator_type": "创作者类型",    // 可选
    "creator_level": "创作者等级",   // 可选
    "creator_category": "创作者分类", // 可选
    "creators_count": 0,            // 可选
    "gmv": "GMV范围",               // 可选
    "followers": "粉丝数范围",       // 可选
    "views": "浏览量范围",           // 可选
    "budget": "预算范围",            // 可选
    "link_product": ["产品ID1"],     // 可选
    "start_date": "开始日期",        // 可选
    "end_date": "结束日期",          // 可选
    "dataset_id": "知识库ID",        // 必填
    "external_id": "外部ID",         // 可选
    "is_active": true               // 可选
  }
  ```
- **响应数据**: 返回创建的活动信息

### 3.3 获取活动详情

- **URL**: `/campaigns/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的活动详细信息
- **请求参数**: 无
- **响应数据**: 返回活动详情

### 3.4 更新活动

- **URL**: `/campaigns/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的活动信息，会自动更新关联品牌的dataset_id_list
- **请求参数**: 同创建活动
- **响应数据**: 返回更新后的活动信息

### 3.5 删除活动

- **URL**: `/campaigns/{id}/`
- **方法**: `DELETE`
- **描述**: 软删除指定ID的活动，并从品牌的dataset_id_list中移除对应的ID
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "删除成功",
    "data": null
  }
  ```

### 3.6 获取Token信息

- **URL**: `/campaigns/token-info/`
- **方法**: `GET`
- **描述**: 获取当前用户的token信息和WebSocket URL示例
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "user_id": 1,
      "email": "user@example.com",
      "token": "token字符串",
      "token_expired_at": "过期时间",
      "websocket_examples": {
        "活动状态WebSocket": "ws://example.com/ws/campaigns/1/status/?token=token字符串",
        "活动产品状态WebSocket": "ws://example.com/ws/campaigns/1/products/123/status/?token=token字符串"
      }
    }
  }
  ```

### 3.7 添加产品到活动

- **URL**: `/campaigns/{id}/add_product/`
- **方法**: `POST`
- **描述**: 将产品添加到活动中
- **请求参数**:
  ```json
  {
    "product_id": "产品ID"  // 必填
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "产品添加成功",
    "data": null
  }
  ```

### 3.8 从活动中移除产品

- **URL**: `/campaigns/{id}/remove_product/`
- **方法**: `POST`
- **描述**: 从活动中移除产品
- **请求参数**:
  ```json
  {
    "product_id": "产品ID"  // 必填
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "产品移除成功",
    "data": null
  }
  ```

### 3.9 获取活动达人列表

- **URL**: `/campaigns/{id}/creator_list/`
- **方法**: `GET`
- **描述**: 获取活动关联的达人列表，并启动状态轮询
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "campaign": {
        "name": "活动名称",
        "description": "活动描述",
        "image_url": "活动图片链接",
        "service": "服务类型",
        "creator_type": "创作者类型",
        "creator_level": "创作者等级",
        "creator_category": "创作者分类",
        "creators_count": 0,
        "gmv": "GMV范围",
        "followers": "粉丝数范围",
        "views": "浏览量范围",
        "budget": "预算范围",
        "start_date": "开始日期",
        "end_date": "结束日期",
        "status": "状态"
      },
      "creators": [
        {
          "name": "达人名称",
          "category": "达人分类",
          "followers": "粉丝数",
          "GMV Generated": "GMV",
          "Views Generated": "观看量",
          "Pricing": "价格",
          "Status": "状态"
        }
      ]
    }
  }
  ```

### 3.10 更新达人状态

- **URL**: `/campaigns/{id}/update_creator_status/`
- **方法**: `POST`
- **描述**: 手动更新达人状态
- **请求参数**:
  ```json
  {
    "creator_id": "达人ID",  // 必填
    "product_id": "产品ID"   // 可选
  }
  ```
- **响应数据**: 返回更新后的达人列表

### 3.11 获取活动产品达人列表

- **URL**: `/campaigns/{id}/product_creators/`
- **方法**: `GET`
- **描述**: 根据活动ID和产品ID获取达人列表，并启动状态轮询
- **请求参数**:
  - `product_id`: 产品ID (可选)
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "campaign_id": "活动ID",
      "product_id": "产品ID",
      "product_name": "产品名称",
      "creators": [
        {
          "creator_name": "达人名称",
          "category": "达人分类",
          "followers": "粉丝数",
          "gmv_generated": "GMV",
          "views_generated": "观看量",
          "pricing": "价格",
          "status": "状态"
        }
      ]
    }
  }
  ```

### 3.12 停止状态轮询

- **URL**: `/campaigns/stop-polling/`
- **方法**: `POST`
- **描述**: 停止指定活动或所有活动的状态轮询
- **请求参数**:
  ```json
  {
    "campaign_id": "活动ID"  // 可选，不提供则停止所有轮询
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "已停止活动轮询",
    "data": null
  }
  ```

### 3.13 获取活动轮询列表

- **URL**: `/campaigns/active-pollings/`
- **方法**: `GET`
- **描述**: 获取当前正在运行的所有轮询任务信息
- **请求参数**: 无
- **响应数据**: 返回活动轮询列表

### 3.14 获取WebSocket连接URL

- **URL**: `/campaigns/{id}/websocket-url/`
- **方法**: `GET`
- **描述**: 获取带认证的WebSocket连接URL
- **请求参数**:
  - `product_id`: 产品ID (可选)
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": {
      "websocket_url": "ws://example.com/ws/campaigns/1/status/?token=token字符串"
    }
  }
  ```

### 3.15 搜索活动

- **URL**: `/campaigns/search/`
- **方法**: `GET`
- **描述**: 根据关键词搜索活动
- **请求参数**:
  - `keyword`: 搜索关键词（必填）
- **搜索说明**:
  - 搜索范围包括：活动名称、活动描述、服务类型、创作者类型、创作者等级、创作者分类、所属品牌名称和活动状态
  - 使用模糊匹配，不区分大小写
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "brand": "品牌ID",
        "brand_name": "品牌名称",
        "name": "活动名称",
        "description": "活动描述",
        "image_url": "活动图片链接",
        "service": "服务类型",
        "creator_type": "创作者类型",
        "creator_level": "创作者等级",
        "creator_category": "创作者分类",
        "creators_count": 0,
        "gmv": "GMV范围",
        "followers": "粉丝数范围",
        "views": "浏览量范围",
        "budget": "预算范围",
        "link_product": ["产品ID1", "产品ID2"],
        "link_product_details": [产品详情对象数组],
        "start_date": "开始日期",
        "end_date": "结束日期",
        "dataset_id": "知识库ID",
        "external_id": "外部ID",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

## 4. 品牌聊天会话管理 (Chat Sessions)

### 4.1 获取聊天会话列表

- **URL**: `/chat-sessions/`
- **方法**: `GET`
- **描述**: 获取所有品牌聊天会话的列表
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "成功",
    "data": [
      {
        "id": "uuid字符串",
        "brand": "品牌ID",
        "brand_name": "品牌名称",
        "session_id": "会话ID",
        "title": "会话标题",
        "dataset_id_list": [],
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true
      }
    ]
  }
  ```

### 4.2 创建聊天会话

- **URL**: `/chat-sessions/`
- **方法**: `POST`
- **描述**: 创建一个新的品牌聊天会话，如果未提供dataset_id_list，则使用品牌的dataset_id_list
- **请求参数**:
  ```json
  {
    "brand": "品牌ID",             // 必填
    "session_id": "会话ID",        // 必填，唯一
    "title": "会话标题",           // 可选，默认"新对话"
    "dataset_id_list": [],         // 可选，默认为品牌的dataset_id_list
    "is_active": true              // 可选，默认true
  }
  ```
- **响应数据**: 返回创建的聊天会话信息

### 4.3 获取聊天会话详情

- **URL**: `/chat-sessions/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的聊天会话详细信息
- **请求参数**: 无
- **响应数据**: 返回聊天会话详情

### 4.4 更新聊天会话

- **URL**: `/chat-sessions/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的聊天会话信息
- **请求参数**: 同创建聊天会话
- **响应数据**: 返回更新后的聊天会话信息

### 4.5 删除聊天会话

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

## 5. WebSocket接口

brands模块提供了WebSocket接口，用于实时获取活动和产品状态更新。

### 5.1 活动状态WebSocket

- **URL**: `ws://domain/ws/campaigns/{campaign_id}/status/?token={token}`
- **描述**: 接收指定活动的状态更新

### 5.2 活动产品状态WebSocket

- **URL**: `ws://domain/ws/campaigns/{campaign_id}/products/{product_id}/status/?token={token}`
- **描述**: 接收指定活动和产品组合的状态更新