677 lines
17 KiB
Markdown
677 lines
17 KiB
Markdown
# 品牌模块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": []
|
||
}
|
||
}
|
||
```
|
||
|
||
## 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
|
||
}
|
||
```
|
||
|
||
## 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字符串"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 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}`
|
||
- **描述**: 接收指定活动和产品组合的状态更新
|