# Template模块API文档

## 概述

Template (模板) 模块用于管理各种模板内容，支持按任务类型、平台、合作模式和服务类型等分类管理模板。主要包括模板分类和模板两大类接口。

## 通用响应格式

所有API响应都遵循以下统一的JSON格式：

```json
{
  "code": 200,      // 状态码，200表示成功，其他值表示错误
  "message": "成功", // 响应消息
  "data": {}        // 响应数据，可能是对象、数组或null
}
```

## 分页响应格式

使用分页的接口将返回以下格式：

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 100,                  // 总记录数
    "next": "下一页URL或null",      // 下一页链接
    "previous": "上一页URL或null",  // 上一页链接
    "results": [],                 // 当前页的数据
    "total_pages": 10,             // 总页数
    "current_page": 1              // 当前页码
  }
}
```

## 认证方式

所有接口都需要使用自定义Token认证，请在HTTP请求头中添加以下字段：

```
Authorization: Token your_token_here
```

## 1. 模板分类管理 (Template Categories)

模板分类用于对模板进行分类和归类，便于管理和检索。

### 1.1 获取模板分类列表

- **URL**: `/categories/`
- **方法**: `GET`
- **描述**: 获取所有模板分类的列表
- **请求参数**:
  - `page`: 页码，默认为1
  - `page_size`: 每页记录数，默认为10，最大为100
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取模板分类列表成功",
    "data": {
      "count": 5,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 1,
          "name": "营销模板",
          "description": "用于营销推广的模板集合",
          "created_at": "2023-06-01T10:00:00Z",
          "updated_at": "2023-06-01T10:00:00Z"
        }
      ],
      "total_pages": 1,
      "current_page": 1
    }
  }
  ```

### 1.2 创建模板分类

- **URL**: `/categories/`
- **方法**: `POST`
- **描述**: 创建一个新的模板分类
- **请求参数**:
  ```json
  {
    "name": "营销模板",              // 必填，分类名称
    "description": "用于营销推广的模板集合"  // 可选，分类描述
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 201,
    "message": "模板分类创建成功",
    "data": {
      "id": 1,
      "name": "营销模板",
      "description": "用于营销推广的模板集合",
      "created_at": "2023-06-01T10:00:00Z",
      "updated_at": "2023-06-01T10:00:00Z"
    }
  }
  ```

### 1.3 获取模板分类详情

- **URL**: `/categories/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的模板分类详情
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取模板分类详情成功",
    "data": {
      "id": 1,
      "name": "营销模板",
      "description": "用于营销推广的模板集合",
      "created_at": "2023-06-01T10:00:00Z",
      "updated_at": "2023-06-01T10:00:00Z"
    }
  }
  ```

### 1.4 更新模板分类

- **URL**: `/categories/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的模板分类信息
- **请求参数**: 同创建模板分类
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "模板分类更新成功",
    "data": {
      "id": 1,
      "name": "更新后的营销模板",
      "description": "这是更新后的描述",
      "created_at": "2023-06-01T10:00:00Z",
      "updated_at": "2023-06-02T10:00:00Z"
    }
  }
  ```

### 1.5 删除模板分类

- **URL**: `/categories/{id}/`
- **方法**: `DELETE`
- **描述**: 删除指定ID的模板分类
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "模板分类删除成功",
    "data": null
  }
  ```

## 2. 模板管理 (Templates)

模板是系统中的核心内容，可以按各种条件进行分类和检索。

### 2.1 获取模板列表

- **URL**: `/`
- **方法**: `GET`
- **描述**: 获取所有模板的列表，支持多种过滤和排序
- **请求参数**:
  - `page`: 页码，默认为1
  - `page_size`: 每页记录数，默认为10，最大为100
  - `title`: 按标题模糊搜索
  - `content`: 按内容模糊搜索
  - `mission`: 按任务类型筛选，可选值：initial_contact, follow_up, negotiation, closing, other
  - `platform`: 按平台筛选，可选值：tiktok, instagram, youtube, facebook, twitter, other
  - `collaboration_type`: 按合作模式筛选，可选值：paid_promotion, affiliate, sponsored_content, brand_ambassador, other
  - `service`: 按服务类型筛选，可选值：voice, text, video, image, other
  - `category`: 按分类ID筛选
  - `category_name`: 按分类名称模糊搜索
  - `is_public`: 按是否公开筛选，true或false
  - `created_after`: 按创建时间筛选，格式：YYYY-MM-DDThh:mm:ssZ
  - `created_before`: 按创建时间筛选，格式：YYYY-MM-DDThh:mm:ssZ
  - `ordering`: 排序字段，可选值：created_at, -created_at, updated_at, -updated_at, title, -title
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取模板列表成功",
    "data": {
      "count": 20,
      "next": null,
      "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-06-01T10:00:00Z",
          "updated_at": "2023-06-01T10:00:00Z"
        }
      ],
      "total_pages": 2,
      "current_page": 1
    }
  }
  ```

### 2.2 创建模板

- **URL**: `/`
- **方法**: `POST`
- **描述**: 创建一个新的模板
- **请求参数**:
  ```json
  {
    "title": "TikTok初次合作邀请",             // 必填，模板标题
    "content": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",  // 必填，模板内容
    "category": 1,                           // 必填，模板分类ID
    "mission": "initial_contact",            // 可选，任务类型，默认为initial_contact
    "platform": "tiktok",                    // 可选，平台，默认为tiktok
    "collaboration_type": "paid_promotion",  // 可选，合作模式，默认为paid_promotion
    "service": "text",                       // 可选，服务类型，默认为text
    "is_public": true                        // 可选，是否公开，默认为true
  }
  ```
- **响应数据**:
  ```json
  {
    "code": 201,
    "message": "模板创建成功",
    "data": {
      "id": 1,
      "title": "TikTok初次合作邀请",
      "content": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
      "category": 1,
      "mission": "initial_contact",
      "platform": "tiktok",
      "service": "text",
      "collaboration_type": "paid_promotion",
      "is_public": true
    }
  }
  ```

### 2.3 获取模板详情

- **URL**: `/{id}/`
- **方法**: `GET`
- **描述**: 获取指定ID的模板详情
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "获取模板详情成功",
    "data": {
      "id": 1,
      "title": "TikTok初次合作邀请",
      "content": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
      "preview": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
      "category": {
        "id": 1,
        "name": "营销模板",
        "description": "用于营销推广的模板集合",
        "created_at": "2023-06-01T10:00:00Z",
        "updated_at": "2023-06-01T10: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-06-01T10:00:00Z",
      "updated_at": "2023-06-01T10:00:00Z"
    }
  }
  ```

### 2.4 更新模板

- **URL**: `/{id}/`
- **方法**: `PUT`/`PATCH`
- **描述**: 更新指定ID的模板信息
- **请求参数**: 同创建模板
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "模板更新成功",
    "data": {
      "id": 1,
      "title": "更新后的TikTok合作邀请",
      "content": "更新后的内容...",
      "category": 1,
      "mission": "follow_up",
      "platform": "tiktok",
      "service": "text",
      "collaboration_type": "paid_promotion",
      "is_public": true
    }
  }
  ```

### 2.5 删除模板

- **URL**: `/{id}/`
- **方法**: `DELETE`
- **描述**: 删除指定ID的模板
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "code": 200,
    "message": "模板删除成功",
    "data": null
  }
  ```

### 2.6 获取我的模板

- **URL**: `/mine/`
- **方法**: `GET`
- **描述**: 获取所有模板，实际上与获取模板列表功能相同
- **请求参数**: 同获取模板列表
- **响应数据**: 同获取模板列表

### 2.7 获取公开模板

- **URL**: `/public/`
- **方法**: `GET`
- **描述**: 获取所有公开的模板
- **请求参数**: 同获取模板列表
- **响应数据**: 同获取模板列表，但只返回is_public=true的模板

### 2.8 按任务类型获取模板

- **URL**: `/by_mission/`
- **方法**: `GET`
- **描述**: 按任务类型获取模板
- **请求参数**:
  - `mission`: 必填，任务类型，可选值：initial_contact, follow_up, negotiation, closing, other
  - 其他参数同获取模板列表
- **响应数据**: 同获取模板列表，但只返回指定任务类型的模板

### 2.9 按平台获取模板

- **URL**: `/by_platform/`
- **方法**: `GET`
- **描述**: 按平台获取模板
- **请求参数**:
  - `platform`: 必填，平台，可选值：tiktok, instagram, youtube, facebook, twitter, other
  - 其他参数同获取模板列表
- **响应数据**: 同获取模板列表，但只返回指定平台的模板

### 2.10 按合作模式获取模板

- **URL**: `/by_collaboration/`
- **方法**: `GET`
- **描述**: 按合作模式获取模板
- **请求参数**:
  - `collaboration_type`: 必填，合作模式，可选值：paid_promotion, affiliate, sponsored_content, brand_ambassador, other
  - 其他参数同获取模板列表
- **响应数据**: 同获取模板列表，但只返回指定合作模式的模板

### 2.11 按服务类型获取模板

- **URL**: `/by_service/`
- **方法**: `GET`
- **描述**: 按服务类型获取模板
- **请求参数**:
  - `service`: 必填，服务类型，可选值：voice, text, video, image, other
  - 其他参数同获取模板列表
- **响应数据**: 同获取模板列表，但只返回指定服务类型的模板

## 3. 模板字段说明

### 3.1 模板分类字段

| 字段名       | 类型       | 说明         |
|-------------|-----------|-------------|
| id          | 整数       | 分类ID       |
| name        | 字符串     | 分类名称     |
| description | 字符串     | 分类描述     |
| created_at  | 日期时间   | 创建时间     |
| updated_at  | 日期时间   | 更新时间     |

### 3.2 模板字段

| 字段名                      | 类型       | 说明                          |
|----------------------------|-----------|------------------------------|
| id                         | 整数       | 模板ID                       |
| title                      | 字符串     | 模板标题                     |
| content                    | 字符串     | 模板内容                     |
| preview                    | 字符串     | 内容预览，自动生成            |
| category                   | 对象/整数  | 模板分类对象或ID             |
| category_name              | 字符串     | 分类名称                     |
| mission                    | 字符串     | 任务类型代码                 |
| mission_display            | 字符串     | 任务类型显示名称             |
| platform                   | 字符串     | 平台代码                     |
| platform_display           | 字符串     | 平台显示名称                 |
| service                    | 字符串     | 服务类型代码                 |
| service_display            | 字符串     | 服务类型显示名称             |
| collaboration_type         | 字符串     | 合作模式代码                 |
| collaboration_type_display | 字符串     | 合作模式显示名称             |
| is_public                  | 布尔值     | 是否公开                     |
| created_at                 | 日期时间   | 创建时间                     |
| updated_at                 | 日期时间   | 更新时间                     |

## 4. 使用示例

### 4.1 创建一个新的模板分类

```http
POST /api/categories/
Content-Type: application/json
Authorization: Token your_token_here

{
  "name": "电商推广模板",
  "description": "专门用于电商产品推广的各类模板"
}
```

### 4.2 创建一个新的TikTok初次联系模板

```http
POST /api/
Content-Type: application/json
Authorization: Token your_token_here

{
  "title": "TikTok品牌合作初次邀请",
  "content": "亲爱的[创作者名称]，\n\n我是[品牌名称]的[您的姓名]。我们非常欣赏您在TikTok上分享的[内容类型]内容，特别是您关于[具体内容]的视频，展现了很高的创意和专业性。\n\n我们希望能与您合作，进行一次付费推广活动。我们的产品是[产品描述]，我们认为这与您的内容风格和受众非常匹配。\n\n如果您有兴趣，我们可以提供[报酬说明]的报酬，以及[其他福利]。希望能得到您的回复，进一步讨论合作细节。\n\n期待您的回复！\n\n谢谢，\n[您的姓名]\n[品牌名称]",
  "category": 1,
  "mission": "initial_contact",
  "platform": "tiktok",
  "collaboration_type": "paid_promotion",
  "service": "text",
  "is_public": true
}
```

### 4.3 查找所有TikTok平台的文本类模板

```http
GET /api/?platform=tiktok&service=text
Authorization: Token your_token_here
```

### 4.4 按任务类型查询模板

```http
GET /api/by_mission/?mission=follow_up
Authorization: Token your_token_here
```