709 lines
18 KiB
Markdown
709 lines
18 KiB
Markdown
# 模板模块 API 文档
|
||
|
||
## 简介
|
||
|
||
模板模块(template)提供了一系列API，用于管理和使用各种消息、内容模板，支持按分类、平台、任务类型等维度管理模板。所有接口均需要身份验证，使用CustomTokenAuthentication进行认证。
|
||
|
||
本文档详细说明了模板模块中所有接口的使用方法、请求参数和响应结果。
|
||
|
||
## 目录
|
||
|
||
- [模板管理](#模板管理)
|
||
- [模板分类管理](#模板分类管理)
|
||
|
||
## 模板管理
|
||
|
||
模板模块使用REST风格的API，通过TemplateViewSet提供了以下功能：
|
||
|
||
### 1. 获取模板列表
|
||
|
||
**接口说明**：获取所有模板的列表
|
||
|
||
**请求地址**：`GET /template/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
| title | string | 否 | 按标题内容过滤(模糊匹配) |
|
||
| content | string | 否 | 按正文内容过滤(模糊匹配) |
|
||
| mission | string | 否 | 按任务类型过滤 |
|
||
| platform | string | 否 | 按平台过滤 |
|
||
| collaboration_type | string | 否 | 按合作模式过滤 |
|
||
| service | string | 否 | 按服务类型过滤 |
|
||
| category | int | 否 | 按分类ID过滤 |
|
||
| category_name | string | 否 | 按分类名称过滤(模糊匹配) |
|
||
| is_public | boolean | 否 | 按是否公开过滤 |
|
||
| created_after | datetime | 否 | 按创建日期过滤(早于指定日期) |
|
||
| created_before | datetime | 否 | 按创建日期过滤(晚于指定日期) |
|
||
| search | string | 否 | 搜索标题和内容 |
|
||
| ordering | string | 否 | 排序字段，例如：-created_at表示按创建时间降序排序 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板列表成功",
|
||
"data": {
|
||
"count": 100,
|
||
"next": "http://example.com/template/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "模板标题",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 10,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取模板详情
|
||
|
||
**接口说明**：获取单个模板的详细信息
|
||
|
||
**请求地址**：`GET /template/{id}/`
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| id | int | 是 | 模板ID |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "模板标题",
|
||
"content": "模板完整内容...",
|
||
"preview": "模板内容预览...",
|
||
"category": {
|
||
"id": 1,
|
||
"name": "分类名称",
|
||
"description": "分类描述",
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
},
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 创建模板
|
||
|
||
**接口说明**：创建新的模板
|
||
|
||
**请求地址**：`POST /template/`
|
||
|
||
**请求参数**：
|
||
|
||
```json
|
||
{
|
||
"title": "模板标题",
|
||
"content": "模板完整内容...",
|
||
"category": 1,
|
||
"mission": "initial_contact",
|
||
"platform": "tiktok",
|
||
"service": "text",
|
||
"collaboration_type": "paid_promotion",
|
||
"is_public": true
|
||
}
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| title | string | 是 | 模板标题 |
|
||
| content | string | 是 | 模板内容 |
|
||
| category | int | 是 | 分类ID |
|
||
| mission | string | 否 | 任务类型，默认"initial_contact"，可选值: initial_contact(初步联系), follow_up(跟进), negotiation(谈判), closing(成交), other(其他) |
|
||
| platform | string | 否 | 平台，默认"tiktok"，可选值: tiktok, instagram, youtube, facebook, twitter, other |
|
||
| service | string | 否 | 服务类型，默认"text"，可选值: voice(声优-交谈), text(文本), video(视频), image(图片), other(其他) |
|
||
| collaboration_type | string | 否 | 合作模式，默认"paid_promotion"，可选值: paid_promotion(付费推广), affiliate(联盟营销), sponsored_content(赞助内容), brand_ambassador(品牌大使), other(其他) |
|
||
| is_public | boolean | 否 | 是否公开，默认true |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"message": "模板创建成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "模板标题",
|
||
"content": "模板完整内容...",
|
||
"category": 1,
|
||
"mission": "initial_contact",
|
||
"platform": "tiktok",
|
||
"service": "text",
|
||
"collaboration_type": "paid_promotion",
|
||
"is_public": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 更新模板
|
||
|
||
**接口说明**：更新已有的模板
|
||
|
||
**请求地址**：`PUT /template/{id}/` 或 `PATCH /template/{id}/`
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| id | int | 是 | 模板ID |
|
||
|
||
**请求参数**：
|
||
- PUT请求需要提供完整的模板信息
|
||
- PATCH请求可以只提供需要更新的字段
|
||
|
||
```json
|
||
{
|
||
"title": "更新后的模板标题",
|
||
"content": "更新后的模板内容...",
|
||
"category": 2,
|
||
"mission": "follow_up",
|
||
"platform": "instagram",
|
||
"service": "voice",
|
||
"collaboration_type": "affiliate",
|
||
"is_public": false
|
||
}
|
||
```
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板更新成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "更新后的模板标题",
|
||
"content": "更新后的模板内容...",
|
||
"category": 2,
|
||
"mission": "follow_up",
|
||
"platform": "instagram",
|
||
"service": "voice",
|
||
"collaboration_type": "affiliate",
|
||
"is_public": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 删除模板
|
||
|
||
**接口说明**：删除指定的模板
|
||
|
||
**请求地址**：`DELETE /template/{id}/`
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| id | int | 是 | 模板ID |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 6. 获取我的模板
|
||
|
||
**接口说明**：获取当前用户有权限查看的所有模板
|
||
|
||
**请求地址**：`GET /template/mine/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板成功",
|
||
"data": {
|
||
"count": 50,
|
||
"next": "http://example.com/template/mine/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "模板标题",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 5,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 获取公开模板
|
||
|
||
**接口说明**：获取所有公开的模板
|
||
|
||
**请求地址**：`GET /template/public/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取公开模板成功",
|
||
"data": {
|
||
"count": 30,
|
||
"next": "http://example.com/template/public/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "模板标题",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 3,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8. 按任务类型获取模板
|
||
|
||
**接口说明**：按任务类型筛选模板
|
||
|
||
**请求地址**：`GET /template/by_mission/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| mission | string | 是 | 任务类型，可选值: initial_contact(初步联系), follow_up(跟进), negotiation(谈判), closing(成交), other(其他) |
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "按任务类型获取模板成功",
|
||
"data": {
|
||
"count": 20,
|
||
"next": "http://example.com/template/by_mission/?mission=initial_contact&page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "初步联系模板",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 2,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9. 按平台获取模板
|
||
|
||
**接口说明**：按平台筛选模板
|
||
|
||
**请求地址**：`GET /template/by_platform/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| platform | string | 是 | 平台，可选值: tiktok, instagram, youtube, facebook, twitter, other |
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "按平台获取模板成功",
|
||
"data": {
|
||
"count": 15,
|
||
"next": "http://example.com/template/by_platform/?platform=tiktok&page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "TikTok模板",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 2,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10. 按合作方式获取模板
|
||
|
||
**接口说明**：按合作方式筛选模板
|
||
|
||
**请求地址**：`GET /template/by_collaboration/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| collaboration | string | 是 | 合作模式，可选值: paid_promotion(付费推广), affiliate(联盟营销), sponsored_content(赞助内容), brand_ambassador(品牌大使), other(其他) |
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "按合作方式获取模板成功",
|
||
"data": {
|
||
"count": 25,
|
||
"next": "http://example.com/template/by_collaboration/?collaboration=paid_promotion&page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "付费推广模板",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 3,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11. 按服务类型获取模板
|
||
|
||
**接口说明**：按服务类型筛选模板
|
||
|
||
**请求地址**：`GET /template/by_service/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| service | string | 是 | 服务类型，可选值: voice(声优-交谈), text(文本), video(视频), image(图片), other(其他) |
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "按服务类型获取模板成功",
|
||
"data": {
|
||
"count": 18,
|
||
"next": "http://example.com/template/by_service/?service=text&page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "文本模板",
|
||
"preview": "模板内容预览...",
|
||
"category_name": "分类名称",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 2,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## 模板分类管理
|
||
|
||
模板分类管理使用REST风格的API，通过TemplateCategoryViewSet提供了以下功能：
|
||
|
||
### 1. 获取分类列表
|
||
|
||
**接口说明**：获取所有模板分类的列表
|
||
|
||
**请求地址**：`GET /template/categories/`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| page | int | 否 | 分页页码，默认1 |
|
||
| page_size | int | 否 | 每页显示数量，默认10，最大100 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板分类列表成功",
|
||
"data": {
|
||
"count": 8,
|
||
"next": null,
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"name": "分类名称",
|
||
"description": "分类描述",
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 1,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取分类详情
|
||
|
||
**接口说明**：获取单个模板分类的详细信息
|
||
|
||
**请求地址**：`GET /template/categories/{id}/`
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| id | int | 是 | 分类ID |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板分类详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "分类名称",
|
||
"description": "分类描述",
|
||
"created_at": "2023-01-01T00:00:00Z",
|
||
"updated_at": "2023-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 创建分类
|
||
|
||
**接口说明**：创建新的模板分类
|
||
|
||
**请求地址**：`POST /template/categories/`
|
||
|
||
**请求参数**：
|
||
|
||
```json
|
||
{
|
||
"name": "新分类名称",
|
||
"description": "新分类描述"
|
||
}
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| name | string | 是 | 分类名称 |
|
||
| description | string | 否 | 分类描述 |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"message": "模板分类创建成功",
|
||
"data": {
|
||
"id": 2,
|
||
"name": "新分类名称",
|
||
"description": "新分类描述",
|
||
"created_at": "2023-01-02T00:00:00Z",
|
||
"updated_at": "2023-01-02T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 更新分类
|
||
|
||
**接口说明**：更新已有的模板分类
|
||
|
||
**请求地址**：`PUT /template/categories/{id}/` 或 `PATCH /template/categories/{id}/`
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| id | int | 是 | 分类ID |
|
||
|
||
**请求参数**：
|
||
- PUT请求需要提供完整的分类信息
|
||
- PATCH请求可以只提供需要更新的字段
|
||
|
||
```json
|
||
{
|
||
"name": "更新后的分类名称",
|
||
"description": "更新后的分类描述"
|
||
}
|
||
```
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板分类更新成功",
|
||
"data": {
|
||
"id": 2,
|
||
"name": "更新后的分类名称",
|
||
"description": "更新后的分类描述",
|
||
"created_at": "2023-01-02T00:00:00Z",
|
||
"updated_at": "2023-01-03T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 删除分类
|
||
|
||
**接口说明**：删除指定的模板分类
|
||
|
||
**请求地址**：`DELETE /template/categories/{id}/`
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|-------|------|-----|------|
|
||
| id | int | 是 | 分类ID |
|
||
|
||
**响应结果**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板分类删除成功",
|
||
"data": null
|
||
}
|
||
```
|