feat(email): 实现邮件模板系统并添加邮件发送功能

- 新增 EmailTemplateUtil 工具类，用于管理邮件模板和发送逻辑 - 在 MainController 中集成 EmailTemplateUtil，用于发送注册成功邮件 - 添加密码重置和通用通知邮件模板 - 实现邮件发送的降级机制，HTML邮件发送失败时自动发送文本邮件 - 添加邮件模板配置和发送设置配置 - 提供异步发送和模板缓存优化建议
2025-08-28 21:02:47 +08:00
parent 557c18cae8
commit 22079719f0
8 changed files with 1429 additions and 11 deletions
--- a/docs/EMAIL_TEMPLATES.md
+++ b/docs/EMAIL_TEMPLATES.md
@@ -0,0 +1,220 @@
+# 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
+
+```java
+@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工具类（推荐）
+
+```java
+@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://www.gxwebsoft.com/orders/12345",
+    "查看订单"
+);
+```
+
+## 模板特性
+
+### 1. 响应式设计
+- 支持桌面和移动设备
+- 自适应屏幕尺寸
+- 优化的移动端体验
+
+### 2. 品牌一致性
+- 统一的视觉风格
+- 企业Logo和品牌色彩
+- 专业的排版设计
+
+### 3. 安全性
+- 密码信息安全展示
+- 安全提醒和建议
+- 防钓鱼设计
+
+### 4. 用户体验
+- 清晰的信息层次
+- 明显的操作按钮
+- 友好的提示信息
+
+## 自定义模板
+
+### 1. 创建新模板
+1. 在 `src/main/resources/templates/` 目录下创建HTML文件
+2. 使用Beetl语法进行变量绑定
+3. 遵循现有模板的样式规范
+
+### 2. Beetl语法示例
+```html
+<!-- 变量输出 -->
+<span>${username!}</span>
+
+<!-- 条件判断 -->
+<% if(email!) { %>
+<div>邮箱：${email!}</div>
+<% } %>
+
+<!-- 循环 -->
+<% for(item in items!) { %>
+<li>${item.name!}</li>
+<% } %>
+```
+
+### 3. 样式规范
+- 使用内联CSS确保兼容性
+- 遵循响应式设计原则
+- 保持品牌色彩一致性
+
+## 配置说明
+
+### 1. 邮件配置 (`application.yml`)
+```yaml
+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工具类
+- 支持响应式设计和品牌定制