core/docs/EMAIL_TEMPLATES.md

WebSoft 邮件模板系统

概述

WebSoft 邮件模板系统提供了一套专业的HTML邮件模板，用于提升企业品牌影响力和用户体验。系统采用Beetl模板引擎，支持动态数据绑定和响应式设计。

模板列表

1. 注册成功邮件 (register-success.html)

• 用途: 用户注册成功后发送的欢迎邮件
• 特点:
  • 专业的品牌展示
  • 账号信息展示
  • 功能特性介绍
  • 安全提醒
• 变量:
  • username: 用户名
  • phone: 手机号
  • password: 密码
  • email: 邮箱（可选）

2. 密码重置邮件 (password-reset.html)

• 用途: 用户密码重置后发送的通知邮件
• 特点:
  • 安全警告设计
  • 重置信息展示
  • 安全建议
• 变量:
  • username: 用户名
  • phone: 手机号
  • newPassword: 新密码
  • resetTime: 重置时间

3. 通用通知邮件 (notification.html)

• 用途: 系统通知、公告等通用邮件
• 特点:
  • 灵活的内容结构
  • 可选的操作按钮
  • 时间戳显示
• 变量:
  • title: 邮件标题
  • content: 邮件内容
  • greeting: 问候语（可选）
  • infoMessage: 提示信息（可选）
  • actionUrl: 操作链接（可选）
  • actionText: 操作按钮文字（可选）
  • sendTime: 发送时间

使用方法

1. 直接使用EmailRecordService

@Resource
private EmailRecordService emailRecordService;

// 发送HTML邮件
Map<String, Object> data = new HashMap<>();
data.put("username", "张三");
data.put("phone", "13800138000");
data.put("password", "123456");

emailRecordService.sendHtmlEmail(
    "恭喜！您的WebSoft账号已注册成功", 
    "register-success.html", 
    data, 
    new String[]{"user@example.com"}
);

2. 使用EmailTemplateUtil工具类（推荐）

@Resource
private EmailTemplateUtil emailTemplateUtil;

// 发送注册成功邮件
emailTemplateUtil.sendRegisterSuccessEmail(
    "张三", "13800138000", "123456", "user@example.com", 1001
);

// 发送密码重置邮件
emailTemplateUtil.sendPasswordResetEmail(
    "张三", "13800138000", "newPassword123", "user@example.com", 1001
);

// 发送通用通知邮件
emailTemplateUtil.sendNotificationEmail(
    "系统维护通知", 
    "系统将在今晚进行维护，请提前保存工作。", 
    "user@example.com", 
    1001
);

// 发送带操作按钮的通知邮件
emailTemplateUtil.sendNotificationEmailWithAction(
    "订单状态更新", 
    "您的订单已发货", 
    "user@example.com", 
    1001,
    "https://websoft.top/orders/12345",
    "查看订单"
);

模板特性

1. 响应式设计

• 支持桌面和移动设备
• 自适应屏幕尺寸
• 优化的移动端体验

2. 品牌一致性

• 统一的视觉风格
• 企业Logo和品牌色彩
• 专业的排版设计

3. 安全性

• 密码信息安全展示
• 安全提醒和建议
• 防钓鱼设计

4. 用户体验

• 清晰的信息层次
• 明显的操作按钮
• 友好的提示信息

自定义模板

1. 创建新模板

1. 在 src/main/resources/templates/ 目录下创建HTML文件
2. 使用Beetl语法进行变量绑定
3. 遵循现有模板的样式规范

2. Beetl语法示例

<!-- 变量输出 -->
<span>${username!}</span>

<!-- 条件判断 -->
<% if(email!) { %>
<div>邮箱：${email!}</div>
<% } %>

<!-- 循环 -->
<% for(item in items!) { %>
<li>${item.name!}</li>
<% } %>

3. 样式规范

• 使用内联CSS确保兼容性
• 遵循响应式设计原则
• 保持品牌色彩一致性

配置说明

1. 邮件配置 (application.yml)

spring:
  mail:
    host: smtp.qq.com
    port: 587
    username: your-email@qq.com
    password: your-password
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true

2. 模板配置 (email-templates.yml)

• 品牌信息配置
• 链接地址配置
• 样式颜色配置
• 发送设置配置

最佳实践

1. 错误处理

• 实现HTML邮件发送失败时的文本邮件降级
• 记录邮件发送日志
• 提供重试机制

2. 性能优化

• 使用邮件队列异步发送
• 缓存模板编译结果
• 批量发送优化

3. 安全考虑

• 验证收件人邮箱格式
• 防止邮件内容注入
• 敏感信息脱敏处理

故障排除

1. 模板不存在

• 检查模板文件路径
• 确认文件名拼写正确
• 验证classpath配置

2. 变量未显示

• 检查变量名是否正确
• 确认数据是否传递
• 验证Beetl语法

3. 样式问题

• 检查CSS兼容性
• 验证邮件客户端支持
• 测试不同设备显示效果

更新日志

v1.0.0 (2024-08-28)

• 初始版本发布
• 提供注册成功、密码重置、通用通知三种模板
• 实现EmailTemplateUtil工具类
• 支持响应式设计和品牌定制