# 模板模块 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
}
```