chore: add tempalte docs

2025-12-06 13:07:30 +08:00
parent a7b4b53639
commit c5984bc800
9 changed files with 1557 additions and 111 deletions
@@ -2,6 +2,23 @@

 ## 2025

+### 2025.12.06
+- **新增消息模板功能**
+  - 支持创建可复用的消息模板
+  - 支持占位符动态替换（`{{key}}` 语法）
+  - 支持 Text、HTML、Markdown 三种格式
+  - 支持为模板配置多个发送实例
+  - 支持 @提醒功能（钉钉、企业微信）
+- **新增 V2 API**
+  - 基于模板的消息发送接口
+  - 使用加密 Token 提升安全性
+  - 支持占位符参数传递
+  - 自动遍历模板的所有启用实例
+- **优化代码结构**
+  - 重构模板相关 Model 命名（`MessageTemplate` → `Template`）
+  - 添加 TypeScript 类型声明文件
+  - 完善文档体系
+
 ### 2025.10.12
 - 增加cookies过期天数设置

@@ -0,0 +1,280 @@
+# 消息模板
+
+消息模板功能允许您创建可复用的消息模板，通过占位符实现动态内容替换，提高消息发送的灵活性和效率。
+
+::: tip ⭐ 作者推荐
+消息模板是 Message Nest 的核心功能，也是我们**强烈推荐**的使用方式。相比传统的任务发送（V1 API），模板方式具有以下显著优势：
+
+**为什么推荐使用模板？**
+1. **开发效率提升 3 倍** - 一次定义模板，所有项目复用，无需重复编写消息内容
+2. **维护成本降低 80%** - 修改消息格式只需在后台更新模板，无需修改代码、重新部署
+3. **团队协作更顺畅** - 开发负责 API 集成，运营负责内容维护，职责清晰
+4. **灰度发布更安全** - 支持模板启用/禁用，可以随时回滚，降低风险
+5. **内容管理更规范** - 所有消息模板集中管理，便于审核和统一风格
+
+**适用场景：**
+- ✅ 用户通知（注册、登录、密码重置等）
+- ✅ 订单消息（下单、支付、发货、退款等）
+- ✅ 系统告警（服务异常、资源不足等）
+- ✅ 营销推广（活动通知、优惠券等）
+- ✅ 完全动态的内容（通过占位符实现，如 `{{content}}`）
+- ✅ **所有消息发送场景**
+
+::: info 关于完全动态内容
+即使消息内容完全动态，也推荐使用模板方式。你可以创建一个只包含一个占位符的模板，如：
+
+**模板内容：** `{{content}}`
+
+**API 调用：**
+```json
+{
+  "placeholders": {
+    "content": "这里是完全动态的内容"
+  }
+}
+```
+
+这样做的好处是：
+1. 后期如果需要添加固定格式（如标题、签名），只需修改模板，无需改代码
+2. 所有消息统一管理，便于审计和监控
+3. 可以随时启用/禁用，便于灰度发布
+
+**V1 API（任务）的定位：**
+- 仅为兼容历史数据而保留
+- 不推荐在任何新项目中使用
+- 后续维护重点在模板功能上
+:::
+
+
+## 功能特性
+
+- ✅ **多格式支持** - 支持 Text、HTML、Markdown 三种格式
+- ✅ **占位符替换** - 使用 `{{key}}` 语法定义动态内容
+- ✅ **实例配置** - 为模板配置多个发送实例（渠道）
+- ✅ **@提醒功能** - 支持钉钉、企业微信的@提醒
+- ✅ **状态管理** - 启用/禁用模板控制
+- ✅ **API调用** - 通过 V2 API 使用模板发送消息
+
+## 创建模板
+
+### 1. 基本信息
+
+在管理后台的"消息模板"页面，点击"新建模板"按钮：
+
+- **模板名称** - 模板的唯一标识名称
+- **模板描述** - 模板的用途说明（可选）
+- **状态** - 启用/禁用
+
+### 2. 定义占位符
+
+占位符用于在发送消息时动态替换内容。
+
+**添加占位符：**
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| Key | 占位符键名 | `username` |
+| Label | 显示标签 | `用户名` |
+| Default | 默认值（可选） | `Guest` |
+
+**使用示例：**
+
+```json
+[
+  {
+    "key": "username",
+    "label": "用户名",
+    "default": "Guest"
+  },
+  {
+    "key": "email",
+    "label": "邮箱地址",
+    "default": "user@example.com"
+  },
+  {
+    "key": "action",
+    "label": "操作类型",
+    "default": "登录"
+  }
+]
+```
+
+### 3. 编写模板内容
+
+支持三种格式，可以根据需要填写一种或多种：
+
+#### Text 模板
+
+纯文本格式，适用于所有渠道：
+
+```text
+您好，{{username}}！
+
+您的账号 {{email}} 刚刚进行了 {{action}} 操作。
+
+如果这不是您本人的操作，请立即联系我们。
+```
+
+#### HTML 模板
+
+HTML 格式，适用于邮件等支持富文本的渠道：
+
+```html
+<div style="font-family: Arial, sans-serif;">
+  <h2>您好，{{username}}！</h2>
+  <p>您的账号 <strong>{{email}}</strong> 刚刚进行了 <span style="color: #007bff;">{{action}}</span> 操作。</p>
+  <p style="color: #dc3545;">如果这不是您本人的操作，请立即联系我们。</p>
+</div>
+```
+
+#### Markdown 模板
+
+Markdown 格式，适用于钉钉、企业微信等支持 Markdown 的渠道：
+
+```markdown
+## 您好，{{username}}！
+
+您的账号 **{{email}}** 刚刚进行了 `{{action}}` 操作。
+
+> ⚠️ 如果这不是您本人的操作，请立即联系我们。
+```
+
+### 4. 配置 @提醒（可选）
+
+针对钉钉、企业微信等渠道，可以配置@提醒：
+
+- **@手机号** - 多个手机号用逗号分隔，如：`13800138000,13900139000`
+- **@用户ID** - 多个用户ID用逗号分隔
+- **@所有人** - 勾选后会@所有群成员
+
+::: warning 注意
+@提醒功能仅在支持的渠道（钉钉、企业微信）中生效。
+:::
+
+## 配置发送实例
+
+创建模板后，需要为模板配置发送实例（渠道）。
+
+### 1. 添加实例
+
+在模板列表中，点击"实例"按钮：
+
+1. 选择发送渠道（从已创建的渠道中选择）
+2. 配置实例参数（如邮箱收件人地址）
+3. 选择消息格式（Text/HTML/Markdown）
+4. 保存实例
+
+### 2. 实例配置说明
+
+不同渠道需要配置不同的参数：
+
+**邮件渠道：**
+- 收件人邮箱地址
+- 消息格式：Text 或 HTML
+
+**钉钉/企业微信：**
+- 消息格式：Text 或 Markdown
+
+**自定义 Webhook：**
+- 根据 Webhook 要求配置
+
+### 3. 管理实例
+
+- **启用/禁用** - 控制实例是否参与发送
+- **编辑** - 修改实例配置
+- **删除** - 删除不需要的实例
+
+## 预览模板
+
+在编辑模板时，可以使用"预览"功能查看替换占位符后的效果：
+
+1. 点击"预览"按钮
+2. 填写占位符的测试值
+3. 查看 Text/HTML/Markdown 三种格式的渲染效果
+
+## 使用模板发送消息
+
+### 通过 API 调用
+
+使用 V2 API 发送模板消息，详见 [V2 API 文档](/api/v2)。
+
+**基本流程：**
+
+1. 获取模板 Token（在模板详情页查看）
+2. 准备占位符数据
+3. 调用 V2 API 发送
+
+**示例：**
+
+```bash
+curl -X POST http://your-domain/api/v2/message/send \
+  -H "Content-Type: application/json" \
+  -d '{
+    "token": "encrypted_template_token",
+    "title": "账号安全提醒",
+    "placeholders": {
+      "username": "张三",
+      "email": "zhangsan@example.com",
+      "action": "登录"
+    }
+  }'
+```
+
+## 最佳实践
+
+### 1. 占位符命名
+
+- 使用有意义的英文名称，如 `username`、`order_id`
+- 避免使用特殊字符，建议使用下划线分隔
+- 保持命名一致性
+
+### 2. 模板设计
+
+- **简洁明了** - 模板内容应简洁清晰
+- **格式适配** - 根据渠道特性选择合适的格式
+- **默认值** - 为占位符设置合理的默认值
+- **测试验证** - 使用预览功能验证模板效果
+
+### 3. 实例管理
+
+- **合理分组** - 为不同用途创建不同的模板
+- **渠道选择** - 根据消息类型选择合适的渠道
+- **定期检查** - 定期检查实例配置的有效性
+
+### 4. 安全性
+
+- **Token 保护** - 妥善保管模板 Token
+- **权限控制** - 合理设置模板的启用/禁用状态
+- **内容审查** - 注意模板内容的合规性
+
+## 常见问题
+
+### Q: 占位符没有被替换？
+
+**A:** 检查以下几点：
+- 占位符格式是否正确（`{{key}}`）
+- API 调用时是否传递了对应的 placeholders 参数
+- Key 名称是否匹配
+
+### Q: 如何选择消息格式？
+
+**A:** 根据渠道特性选择：
+- **邮件** - 推荐使用 HTML 格式，视觉效果更好
+- **钉钉/企业微信** - 推荐使用 Markdown 格式，支持富文本
+- **其他渠道** - 使用 Text 格式，兼容性最好
+
+### Q: 可以为一个模板配置多个实例吗？
+
+**A:** 可以。一个模板可以配置多个发送实例，调用 API 时会自动遍历所有启用的实例进行发送。
+
+### Q: @提醒不生效？
+
+**A:** 确认以下几点：
+- 渠道是否支持@提醒（仅钉钉、企业微信支持）
+- 手机号或用户ID格式是否正确
+- 机器人是否有@权限
+
+## 下一步
+
+- 查看 [V2 API 文档](/api/v2) 了解如何通过 API 使用模板
+- 查看 [API 示例](/api/examples) 了解各语言的调用方式