J/daren
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d13b21e284
daren/template.md

709 lines
18 KiB
Markdown
Raw Normal View History

添加单个单人简易信息
2025-05-23 20:35:52 +08:00
# 模板模块 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
}
```
Reference in New Issue Copy Permalink