diff --git a/apps/brands/brands.md b/apps/brands/brands.md new file mode 100644 index 0000000..4748e2e --- /dev/null +++ b/apps/brands/brands.md @@ -0,0 +1,719 @@ +# 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 +``` + +### 响应格式 + +所有 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" + } + ] + } + } + ``` diff --git a/apps/brands/consumers.py b/apps/brands/consumers.py index da7c559..67479c2 100644 --- a/apps/brands/consumers.py +++ b/apps/brands/consumers.py @@ -216,6 +216,10 @@ class CampaignStatusConsumer(WebsocketConsumer): if not status: status = cc.status + # 如果状态仍然为空，设置默认值"Unconnected" + if not status: + status = "Unconnected" + # 构建响应数据 creator_data = { "creator_name": creator.name, diff --git a/apps/brands/views.py b/apps/brands/views.py index 084cd74..5bd4849 100644 --- a/apps/brands/views.py +++ b/apps/brands/views.py @@ -19,13 +19,13 @@ from .services.offer_status_service import OfferStatusService logger = logging.getLogger(__name__) -def api_response(code=200, message="成功", data=None): +def api_response(code=200, message="成功", data=None, headers=None): """统一API响应格式""" return Response({ 'code': code, 'message': message, 'data': data - }) + }, headers=headers) class BrandViewSet(viewsets.ModelViewSet): @@ -40,6 +40,14 @@ class BrandViewSet(viewsets.ModelViewSet): return BrandDetailSerializer return BrandSerializer + def create(self, request, *args, **kwargs): + serializer = self.get_serializer(data=request.data) + if serializer.is_valid(): + self.perform_create(serializer) + headers = self.get_success_headers(serializer.data) + return api_response(data=serializer.data, headers=headers) + return api_response(code=400, message="创建失败", data=serializer.errors) + def list(self, request, *args, **kwargs): queryset = self.filter_queryset(self.get_queryset()) serializer = self.get_serializer(queryset, many=True) @@ -99,6 +107,14 @@ class ProductViewSet(viewsets.ModelViewSet): serializer = self.get_serializer(queryset, many=True) return api_response(data=serializer.data) + def create(self, request, *args, **kwargs): + serializer = self.get_serializer(data=request.data) + if serializer.is_valid(): + self.perform_create(serializer) + headers = self.get_success_headers(serializer.data) + return api_response(data=serializer.data, headers=headers) + return api_response(code=400, message="创建失败", data=serializer.errors) + def retrieve(self, request, *args, **kwargs): instance = self.get_object() serializer = self.get_serializer(instance) @@ -215,6 +231,14 @@ class CampaignViewSet(viewsets.ModelViewSet): serializer = self.get_serializer(queryset, many=True) return api_response(data=serializer.data) + def create(self, request, *args, **kwargs): + serializer = self.get_serializer(data=request.data) + if serializer.is_valid(): + self.perform_create(serializer) + headers = self.get_success_headers(serializer.data) + return api_response(data=serializer.data, headers=headers) + return api_response(code=400, message="创建失败", data=serializer.errors) + def retrieve(self, request, *args, **kwargs): instance = self.get_object() serializer = self.get_serializer(instance) @@ -726,6 +750,14 @@ class BrandChatSessionViewSet(viewsets.ModelViewSet): serializer = self.get_serializer(queryset, many=True) return api_response(data=serializer.data) + def create(self, request, *args, **kwargs): + serializer = self.get_serializer(data=request.data) + if serializer.is_valid(): + self.perform_create(serializer) + headers = self.get_success_headers(serializer.data) + return api_response(data=serializer.data, headers=headers) + return api_response(code=400, message="创建失败", data=serializer.errors) + def retrieve(self, request, *args, **kwargs): instance = self.get_object() serializer = self.get_serializer(instance) diff --git a/apps/discovery/discovery.md b/apps/discovery/discovery.md new file mode 100644 index 0000000..fc480b8 --- /dev/null +++ b/apps/discovery/discovery.md @@ -0,0 +1,371 @@ +# Discovery 模块 API 文档 + +本文档详细说明了 Discovery 模块的 API 接口，包括请求方法、URL、参数说明和响应格式。 + +## 目录 + +1. [通用说明](#通用说明) +2. [创作者搜索会话接口](#创作者搜索会话接口) +3. [创作者发现接口](#创作者发现接口) + +## 通用说明 + +### 基础URL + +所有 API 的基础 URL 为：`http://127.0.0.1:8000/api/discovery/` + +### 认证方式 + +所有 API 都需要 Token 认证。请在请求头中添加： + +``` +Authorization: Token +``` + +### 响应格式 + +所有 API 返回的数据格式统一为： + +```json +{ + "code": 200, // 状态码，200表示成功，其他表示错误 + "message": "成功", // 状态描述 + "data": {} // 返回的数据，可能是对象、数组或null +} +``` + +### 分页 + +列表接口支持分页，默认每页 20 条数据，最大每页 100 条。 + +分页参数： +- `page`: 页码，从1开始 +- `page_size`: 每页数量，默认20 + +分页响应格式： + +```json +{ + "code": 200, + "message": "获取数据成功", + "data": { + "count": 100, // 总记录数 + "next": "下一页URL", // 下一页链接，如果没有则为null + "previous": "上一页URL", // 上一页链接，如果没有则为null + "results": [] // 当前页数据 + } +} +``` + +## 创作者搜索会话接口 + +搜索会话是指用户进行的一次创作者搜索，包含搜索结果和相关统计信息。 + +### 获取搜索会话列表 + +- **URL**: `/sessions/` +- **方法**: GET +- **描述**: 获取所有搜索会话的列表 +- **参数**: + - 分页参数，参见[分页](#分页)部分 +- **响应示例**: + ```json + { + "code": 200, + "message": "获取搜索会话列表成功", + "data": [ + { + "id": 1, + "session_number": 123, + "creator_count": 100, + "shoppable_creators": 26, + "avg_followers": 162.2, + "avg_gmv": 534.1, + "avg_video_views": 1.9, + "date_created": "2023-01-01" + } + ] + } + ``` + +### 获取搜索会话详情 + +- **URL**: `/sessions/{session_id}/` +- **方法**: GET +- **描述**: 获取指定ID的搜索会话详细信息，包含搜索到的创作者列表 +- **参数**: + - `session_id`: 会话ID (路径参数) +- **响应示例**: + ```json + { + "code": 200, + "message": "获取搜索会话详情成功", + "data": { + "id": 1, + "session_number": 123, + "creator_count": 100, + "shoppable_creators": 26, + "avg_followers": 162.2, + "avg_gmv": 534.1, + "avg_video_views": 1.9, + "date_created": "2023-01-01", + "creators": [ + // 创作者列表，见创作者数据结构 + ] + } + } + ``` + +### 创建搜索会话 + +- **URL**: `/sessions/` +- **方法**: POST +- **描述**: 创建新的搜索会话 +- **请求参数**: + ```json + { + "session_number": 123, + "creator_count": 100, + "shoppable_creators": 26, + "avg_followers": 162.2, + "avg_gmv": 534.1, + "avg_video_views": 1.9, + "date_created": "2023-01-01" + } + ``` +- **响应示例**: + ```json + { + "code": 200, + "message": "创建搜索会话成功", + "data": { + "id": 1, + "session_number": 123, + "creator_count": 100, + "shoppable_creators": 26, + "avg_followers": 162.2, + "avg_gmv": 534.1, + "avg_video_views": 1.9, + "date_created": "2023-01-01" + } + } + ``` + +### 更新搜索会话 + +- **URL**: `/sessions/{session_id}/` +- **方法**: PUT/PATCH +- **描述**: 更新搜索会话信息 +- **参数**: + - `session_id`: 会话ID (路径参数) + - 请求体包含要更新的字段 +- **响应示例**: + ```json + { + "code": 200, + "message": "更新搜索会话成功", + "data": { + // 更新后的会话信息 + } + } + ``` + +### 删除搜索会话 + +- **URL**: `/sessions/{session_id}/` +- **方法**: DELETE +- **描述**: 删除搜索会话 +- **参数**: + - `session_id`: 会话ID (路径参数) +- **响应示例**: + ```json + { + "code": 200, + "message": "删除搜索会话成功", + "data": null + } + ``` + +### 获取会话创作者列表 + +- **URL**: `/sessions/{session_id}/results/` +- **方法**: GET +- **描述**: 获取指定会话的搜索结果（创作者列表） +- **参数**: + - `session_id`: 会话ID (路径参数) + - 分页参数，参见[分页](#分页)部分 +- **响应示例**: + ```json + { + "code": 200, + "message": "获取会话创作者列表成功", + "data": [ + // 创作者列表，见创作者数据结构 + ] + } + ``` + +## 创作者发现接口 + +### 获取创作者列表 + +- **URL**: `/creators/` +- **方法**: GET +- **描述**: 获取所有创作者的列表 +- **参数**: + - 分页参数，参见[分页](#分页)部分 +- **响应示例**: + ```json + { + "code": 200, + "message": "获取创作者列表成功", + "data": [ + { + "id": 1, + "name": "创作者名称", + "avatar": "头像URL", + "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": "抖音链接", + "session": 1 + } + ] + } + ``` + +### 获取创作者详情 + +- **URL**: `/creators/{creator_id}/` +- **方法**: GET +- **描述**: 获取指定ID的创作者详细信息 +- **参数**: + - `creator_id`: 创作者ID (路径参数) +- **响应示例**: + ```json + { + "code": 200, + "message": "获取创作者详情成功", + "data": { + "id": 1, + "name": "创作者名称", + "avatar": "头像URL", + "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": "抖音链接", + "session": 1 + } + } + ``` + +### 搜索创作者 + +- **URL**: `/creators/search/` +- **方法**: POST +- **描述**: 根据条件搜索创作者并创建新的搜索会话 +- **请求参数**: + ```json + { + "query": "搜索关键词", + "category": "Phones & Electronics", // 可选，见类别列表 + "ecommerce_level": "L2", // 可选，见电商等级列表 + "exposure_level": "KOC-1" // 可选，见曝光等级列表 + } + ``` +- **响应示例**: + ```json + { + "code": 200, + "message": "搜索创作者成功", + "data": { + "id": 1, + "session_number": 123, + "creator_count": 5, + "shoppable_creators": 3, + "avg_followers": 162.2, + "avg_gmv": 534.1, + "avg_video_views": 1.9, + "date_created": "2023-01-01", + "creators": [ + // 创作者列表，见创作者数据结构 + ] + } + } + ``` + +## 数据结构 + +### 创作者类别 + +- `Phones & Electronics`: 手机与电子产品 +- `Womenswear & Underwear`: 女装与内衣 +- `Sports & Outdoor`: 运动与户外 +- `Food & Beverage`: 食品与饮料 +- `Health`: 健康 +- `Kitchenware`: 厨具 +- `Furniture`: 家具 +- `Shoes`: 鞋类 +- `Home Supplies`: 家居用品 + +### 电商等级 + +- `L1`: Level 1 +- `L2`: Level 2 +- `L3`: Level 3 +- `L4`: Level 4 +- `L5`: Level 5 +- `New tag`: 新标签 + +### 曝光等级 + +- `KOC-1`: Key Opinion Consumer 1级 +- `KOC-2`: Key Opinion Consumer 2级 +- `KOL-2`: Key Opinion Leader 2级 +- `KOL-3`: Key Opinion Leader 3级 +- `New tag`: 新标签 + +### 创作者数据结构 + +```json +{ + "id": 1, + "name": "创作者名称", + "avatar": "头像URL", + "category": "Phones & Electronics", + "ecommerce_level": "L2", + "exposure_level": "KOC-1", + "followers": 162.2, // 单位：K (千) + "gmv": 534.1, // 单位：K (千) + "items_sold": 18.1, // 单位：K (千) + "avg_video_views": 1.9, // 单位：M (百万) + "has_ecommerce": true, // 是否有电商能力 + "tiktok_url": "抖音链接", + "session": 1 // 所属搜索会话ID +} +``` + +### 搜索会话数据结构 + +```json +{ + "id": 1, + "session_number": 123, // 会话编号 + "creator_count": 100, // 创作者数量 + "shoppable_creators": 26, // 可购物创作者数量 + "avg_followers": 162.2, // 平均粉丝数 (K) + "avg_gmv": 534.1, // 平均GMV (K) + "avg_video_views": 1.9, // 平均视频观看量 (M) + "date_created": "2023-01-01" // 创建日期 +} +```