ai-engineering-init 1.7.0 → 1.10.0

package/.codex/skills/sms-mail/SKILL.md

@@ -1,239 +1,300 @@
 ---
 name: sms-mail
 description: |
-  当需要发送短信、邮件通知时自动使用此 Skill。
-
+  通用短信邮件开发指南。涵盖抽象接口模式、多渠道切换策略、验证码流程、模板消息。
   触发场景：
-  - 需要发送短信验证码
-  - 需要发送邮件通知（文本/HTML）
-  - 需要配置短信服务商（阿里云/腾讯云/华为云等）
-  - 需要配置邮件服务器（SMTP）
-  - 需要实现多渠道消息通知
-
-  触发词：短信、邮件、SMS、验证码、通知、SMS4j、MailUtils、邮件发送、短信发送、SmsBlend、SmsFactory、SMTP、模板消息
+  - 发送短信验证码
+  - 发送邮件通知（文本/HTML/附件）
+  - 配置短信服务商（阿里云/腾讯云等）
+  - 配置邮件服务器（SMTP）
+  - 实现多渠道消息通知
+  触发词：短信、邮件、SMS、验证码、通知、邮件发送、短信发送、SMTP、模板消息、多渠道
+  注意：如果项目有专属技能，优先使用专属版本。
 ---
 
 # 短信与邮件开发指南
 
-> 短信模块：`ruoyi-common/ruoyi-common-sms`（SMS4j）
-> 邮件模块：`ruoyi-common/ruoyi-common-mail`（Hutool JakartaMail）
+> 通用模板。如果项目有专属技能，优先使用。
 
----
+## 设计原则
 
-## 一、短信开发（SMS4j）
+1. **接口抽象**：定义统一的发送接口，具体渠道通过策略模式实现，方便切换供应商。
+2. **异步发送**：发送操作应异步执行，不阻塞主业务流程。
+3. **结果校验**：每次发送必须检查返回结果，失败需记录日志并决策是否重试。
+4. **安全防护**：验证码需限频限量、设置过期时间，防止短信轰炸和暴力破解。
 
-### 1.1 配置
-
-```yaml
-sms:
-  config-type: yaml   # yaml / 接口 / 数据库
-  blends:
-    config1:
-      supplier: alibaba
-      access-key-id: ${ALIYUN_SMS_ACCESS_KEY_ID}
-      access-key-secret: ${ALIYUN_SMS_ACCESS_KEY_SECRET}
-      signature: 若依框架
-    config2:
-      supplier: tencent
-      access-key-id: ${TENCENT_SMS_SECRET_ID}
-      access-key-secret: ${TENCENT_SMS_SECRET_KEY}
-      signature: 若依框架
-      sdk-app-id: "1400000000"   # 腾讯云需要
-```
+---
 
-> 支持的服务商：alibaba / tencent / huawei / yunpian / unisms / jdcloud / cloopen / emay / ctyun
-> 限流配置详见 [references/sms-config.md](references/sms-config.md)
+## 实现模式
 
-### 1.2 核心 API
+### 一、抽象接口设计
 
 ```java
-import org.dromara.sms4j.api.SmsBlend;
-import org.dromara.sms4j.api.entity.SmsResponse;
-import org.dromara.sms4j.core.factory.SmsFactory;
-
-// 获取短信实例
-SmsBlend smsBlend = SmsFactory.getSmsBlend();            // 默认配置
-SmsBlend smsBlend = SmsFactory.getSmsBlend("config1");   // 指定配置
-
-// 发送模板短信
-Map<String, String> params = new LinkedHashMap<>();
-params.put("code", "123456");
-params.put("time", "5");
-SmsResponse response = smsBlend.sendMessage("13800138000", "SMS_123456789", params);
-
-// 批量发送
-List<String> phones = Arrays.asList("13800138001", "13800138002");
-SmsResponse response = smsBlend.sendMessage(phones, "SMS_123456789", params);
-
-// 检查结果
-if (response.isSuccess()) {
-    log.info("发送成功，msgId: {}", response.getBizId());
-} else {
-    log.error("发送失败：{}", response.getMessage());
+// 统一短信发送接口
+public interface SmsSender {
+    SmsResult send(String phone, String templateId, Map<String, String> params);
+    SmsResult batchSend(List<String> phones, String templateId, Map<String, String> params);
 }
-```
 
-### 1.3 验证码短信示例
+// 统一邮件发送接口
+public interface MailSender {
+    String sendText(String to, String subject, String content);
+    String sendHtml(String to, String subject, String htmlContent);
+    String sendWithAttachment(String to, String subject, String content, File... files);
+}
 
-```java
-@RestController
-@RequestMapping("/captcha")
-@RequiredArgsConstructor
-public class CaptchaController {
+// 发送结果
+@Data
+public class SmsResult {
+    private boolean success;
+    private String messageId;
+    private String errorMessage;
+}
+```
 
-    @GetMapping("/sms")
-    public R<Void> sendSmsCode(@RequestParam String phonenumber) {
-        String code = RandomUtil.randomNumbers(6);
+### 二、短信服务
 
-        // 存入Redis（5分钟有效）
-        RedisUtils.setCacheObject("sms:code:" + phonenumber, code, Duration.ofMinutes(5));
+#### 多渠道策略模式
 
-        // 发送短信
-        Map<String, String> map = new LinkedHashMap<>();
-        map.put("code", code);
-        SmsBlend smsBlend = SmsFactory.getSmsBlend("config1");
-        SmsResponse smsResponse = smsBlend.sendMessage(phonenumber, "SMS_123456789", map);
+```java
+// 阿里云实现
+@Service("aliyunSmsSender")
+public class AliyunSmsSender implements SmsSender {
+    @Override
+    public SmsResult send(String phone, String templateId, Map<String, String> params) {
+        // 调用阿里云 SMS SDK
+    }
+}
 
-        if (!smsResponse.isSuccess()) {
-            log.error("短信发送失败：{}", smsResponse.getMessage());
-            return R.fail("短信发送失败");
-        }
-        return R.ok("验证码已发送");
+// 腾讯云实现
+@Service("tencentSmsSender")
+public class TencentSmsSender implements SmsSender {
+    @Override
+    public SmsResult send(String phone, String templateId, Map<String, String> params) {
+        // 调用腾讯云 SMS SDK
     }
+}
 
-    @PostMapping("/verify")
-    public R<Boolean> verifySmsCode(@RequestParam String phonenumber,
-                                     @RequestParam String code) {
-        String cacheKey = "sms:code:" + phonenumber;
-        String cachedCode = RedisUtils.getCacheObject(cacheKey);
+// 工厂/路由
+@Service
+public class SmsService {
+
+    @Autowired
+    private Map<String, SmsSender> senderMap;
 
-        if (cachedCode == null) return R.fail("验证码已过期");
-        if (!cachedCode.equals(code)) return R.fail("验证码错误");
+    @Value("${sms.default-channel:aliyunSmsSender}")
+    private String defaultChannel;
 
-        RedisUtils.deleteObject(cacheKey);
-        return R.ok(true);
+    public SmsResult send(String phone, String templateId, Map<String, String> params) {
+        SmsSender sender = senderMap.get(defaultChannel);
+        if (sender == null) {
+            throw new [你的异常类]("短信渠道未配置: " + defaultChannel);
+        }
+        SmsResult result = sender.send(phone, templateId, params);
+        if (!result.isSuccess()) {
+            log.error("短信发送失败: phone={}, error={}", phone, result.getErrorMessage());
+        }
+        return result;
     }
 }
 ```
 
----
-
-## 二、邮件开发（Hutool Mail）
-
-### 2.1 配置
+#### 配置示例
 
 ```yaml
-mail:
-  enabled: true
-  host: smtp.163.com
-  port: 465
-  auth: true
-  from: system@example.com
-  user: system@example.com
-  pass: ${MAIL_PASSWORD}        # 授权码，非登录密码
-  sslEnable: true
-  starttlsEnable: false
-  timeout: 10000
-  connectionTimeout: 10000
+sms:
+  default-channel: aliyunSmsSender
+  aliyun:
+    access-key-id: ${ALIYUN_SMS_KEY:}
+    access-key-secret: ${ALIYUN_SMS_SECRET:}
+    sign-name: [你的签名]
+  tencent:
+    secret-id: ${TENCENT_SMS_ID:}
+    secret-key: ${TENCENT_SMS_KEY:}
+    sdk-app-id: "1400000000"
+    sign-name: [你的签名]
 ```
 
-> 常用 SMTP 服务器配置详见 [references/mail-config.md](references/mail-config.md)
-
-### 2.2 核心 API
+#### 验证码短信完整示例
 
 ```java
-import org.dromara.common.mail.utils.MailUtils;
+@RestController
+@RequestMapping("/captcha")
+public class CaptchaController {
 
-// 发送文本邮件
-String msgId = MailUtils.sendText("to@example.com", "标题", "正文内容");
+    @Autowired
+    private SmsService smsService;
 
-// 发送HTML邮件
-String msgId = MailUtils.sendHtml("to@example.com", "标题", "<h1>内容</h1>");
+    @Autowired
+    private StringRedisTemplate redisTemplate;
 
-// 带附件
-String msgId = MailUtils.sendText("to@example.com", "标题", "正文", attachment);
-String msgId = MailUtils.sendHtml("to@example.com", "标题", htmlContent, attachment);
+    @GetMapping("/sms")
+    public Result<?> sendSmsCode(@RequestParam String phone) {
+        // 1. 限频检查（60秒内只能发一次）
+        String limitKey = "sms:limit:" + phone;
+        if (Boolean.TRUE.equals(redisTemplate.hasKey(limitKey))) {
+            return Result.fail("请60秒后重试");
+        }
 
-// 带内嵌图片
-Map<String, InputStream> imageMap = Map.of("logo", new FileInputStream("logo.png"));
-String msgId = MailUtils.sendHtml("to@example.com", "标题",
-    "<img src='cid:logo'/>", imageMap);
+        // 2. 生成验证码
+        String code = String.valueOf(ThreadLocalRandom.current().nextInt(100000, 999999));
 
-// 群发
-String msgId = MailUtils.sendHtml(List.of("a@x.com", "b@x.com"), "标题", htmlContent);
+        // 3. 存入 Redis（5分钟有效）
+        String codeKey = "sms:code:" + phone;
+        redisTemplate.opsForValue().set(codeKey, code, 5, TimeUnit.MINUTES);
+        redisTemplate.opsForValue().set(limitKey, "1", 60, TimeUnit.SECONDS);
 
-// 抄送/密送
-String msgId = MailUtils.send("to@x.com", "cc@x.com", "bcc@x.com", "标题", "内容", true);
+        // 4. 发送短信
+        Map<String, String> params = new LinkedHashMap<>();
+        params.put("code", code);
+        SmsResult result = smsService.send(phone, "SMS_VERIFY_CODE", params);
 
-// 获取邮件账户配置
-MailAccount account = MailUtils.getMailAccount();
+        if (!result.isSuccess()) {
+            redisTemplate.delete(codeKey);
+            return Result.fail("短信发送失败");
+        }
+        return Result.ok("验证码已发送");
+    }
+
+    @PostMapping("/verify")
+    public Result<Boolean> verify(@RequestParam String phone, @RequestParam String code) {
+        String codeKey = "sms:code:" + phone;
+        String cached = redisTemplate.opsForValue().get(codeKey);
+
+        if (cached == null) return Result.fail("验证码已过期");
+        if (!cached.equals(code)) return Result.fail("验证码错误");
+
+        redisTemplate.delete(codeKey);
+        return Result.ok(true);
+    }
+}
 ```
 
-### 2.3 邮件验证码示例
+---
+
+### 三、邮件服务
+
+#### Spring Boot 原生邮件
 
 ```java
 @Service
-@RequiredArgsConstructor
-public class EmailService {
-
-    public void sendEmailCode(String email) {
-        String code = RandomUtil.randomNumbers(6);
-        RedisUtils.setCacheObject("email:code:" + email, code, Duration.ofMinutes(10));
-
-        String htmlContent = String.format("""
-            <div style="padding: 20px; background: #f5f5f5;">
-                <h2>验证码</h2>
-                <p>您的验证码是：<strong style="color: #1890ff; font-size: 24px;">%s</strong></p>
-                <p>有效期10分钟，请勿泄露。</p>
-            </div>
-            """, code);
-
-        try {
-            MailUtils.sendHtml(email, "【若依系统】验证码", htmlContent);
-        } catch (Exception e) {
-            log.error("邮件发送失败：{}", e.getMessage());
-            throw new ServiceException("邮件发送失败");
-        }
+public class MailService {
+
+    @Autowired
+    private JavaMailSender mailSender;
+
+    @Value("${spring.mail.username}")
+    private String from;
+
+    // 文本邮件
+    public void sendText(String to, String subject, String content) {
+        SimpleMailMessage message = new SimpleMailMessage();
+        message.setFrom(from);
+        message.setTo(to);
+        message.setSubject(subject);
+        message.setText(content);
+        mailSender.send(message);
     }
 
-    public boolean verifyEmailCode(String email, String code) {
-        String cacheKey = "email:code:" + email;
-        String cachedCode = RedisUtils.getCacheObject(cacheKey);
-        if (cachedCode != null && cachedCode.equals(code)) {
-            RedisUtils.deleteObject(cacheKey);
-            return true;
+    // HTML 邮件
+    public void sendHtml(String to, String subject, String htmlContent) throws MessagingException {
+        MimeMessage message = mailSender.createMimeMessage();
+        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
+        helper.setFrom(from);
+        helper.setTo(to);
+        helper.setSubject(subject);
+        helper.setText(htmlContent, true);
+        mailSender.send(message);
+    }
+
+    // 带附件邮件
+    public void sendWithAttachment(String to, String subject, String content,
+                                    File... attachments) throws MessagingException {
+        MimeMessage message = mailSender.createMimeMessage();
+        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
+        helper.setFrom(from);
+        helper.setTo(to);
+        helper.setSubject(subject);
+        helper.setText(content, true);
+        for (File file : attachments) {
+            helper.addAttachment(file.getName(), file);
         }
-        return false;
+        mailSender.send(message);
+    }
+
+    // 群发
+    public void sendHtml(List<String> toList, String subject, String htmlContent)
+            throws MessagingException {
+        MimeMessage message = mailSender.createMimeMessage();
+        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
+        helper.setFrom(from);
+        helper.setTo(toList.toArray(new String[0]));
+        helper.setSubject(subject);
+        helper.setText(htmlContent, true);
+        mailSender.send(message);
     }
 }
 ```
 
+#### 配置示例
+
+```yaml
+spring:
+  mail:
+    host: smtp.163.com
+    port: 465
+    username: system@example.com
+    password: ${MAIL_PASSWORD}    # 授权码，非登录密码
+    properties:
+      mail:
+        smtp:
+          auth: true
+          ssl:
+            enable: true
+          timeout: 10000
+          connectiontimeout: 10000
+```
+
+常用 SMTP 服务器：
+
+| 提供商 | Host | 端口(SSL) |
+|--------|------|----------|
+| 163 | smtp.163.com | 465 |
+| QQ | smtp.qq.com | 465 |
+| Gmail | smtp.gmail.com | 465 |
+| 阿里企业邮箱 | smtp.qiye.aliyun.com | 465 |
+
 ---
 
-## 三、多渠道消息通知示例
+### 四、多渠道消息通知
 
 ```java
 @Service
-@RequiredArgsConstructor
 public class MessageService {
 
-    public void sendMessage(List<String> messageType, String subject,
-                           String message, List<UserDTO> userList) {
-        for (UserDTO user : userList) {
+    @Autowired
+    private SmsService smsService;
+
+    @Autowired
+    private MailService mailService;
+
+    // 可扩展：站内信、推送、企业微信等
+    public void sendNotification(List<String> channels, String subject,
+                                  String content, List<UserDTO> users) {
+        for (UserDTO user : users) {
             try {
-                if (messageType.contains("sms") && StringUtils.isNotBlank(user.getPhone())) {
-                    Map<String, String> params = new LinkedHashMap<>();
-                    params.put("content", message);
-                    SmsFactory.getSmsBlend("config1")
-                        .sendMessage(user.getPhone(), "SMS_NOTIFY", params);
+                if (channels.contains("sms") && StringUtils.hasText(user.getPhone())) {
+                    Map<String, String> params = Map.of("content", content);
+                    smsService.send(user.getPhone(), "SMS_NOTIFY", params);
                 }
-                if (messageType.contains("email") && StringUtils.isNotBlank(user.getEmail())) {
-                    MailUtils.sendHtml(user.getEmail(), subject,
-                        "<div style='padding:20px;'><h3>" + subject + "</h3><p>" + message + "</p></div>");
+                if (channels.contains("email") && StringUtils.hasText(user.getEmail())) {
+                    mailService.sendHtml(user.getEmail(), subject,
+                        "<div style='padding:20px;'><h3>" + subject + "</h3><p>" + content + "</p></div>");
                 }
             } catch (Exception e) {
-                log.error("消息发送失败，类型：{}，用户：{}，错误：{}",
-                    messageType, user.getUserId(), e.getMessage());
+                log.error("消息发送失败, channel={}, userId={}, error={}",
+                    channels, user.getUserId(), e.getMessage());
+                // 不抛出，继续发送其他用户
             }
         }
     }
@@ -242,67 +303,44 @@ public class MessageService {
 
 ---
 
-## 四、常见错误
+## 选型建议
 
-```java
-// ❌ 未配置就使用，getSmsBlend 返回 null → NPE
-SmsBlend smsBlend = SmsFactory.getSmsBlend("config1");
-smsBlend.sendMessage(...);
-
-// ❌ 模板参数名与模板定义不匹配
-params.put("verifyCode", "123456");  // 模板中是 ${code}
-// ✅ params.put("code", "123456");
-
-// ❌ 不检查发送结果
-smsBlend.sendMessage(phone, templateId, params);
-// ✅ SmsResponse response = smsBlend.sendMessage(...);
-//    if (!response.isSuccess()) throw new ServiceException("短信发送失败");
-
-// ❌ 验证码无过期时间
-RedisUtils.setCacheObject("sms:code:" + phone, code);
-// ✅ RedisUtils.setCacheObject("sms:code:" + phone, code, Duration.ofMinutes(5));
-```
+| 维度 | 自研抽象层 | SMS4j | 云 SDK 直接调用 |
+|------|----------|-------|----------------|
+| 灵活性 | 最高 | 高 | 中 |
+| 开发成本 | 中 | 低 | 低 |
+| 多渠道切换 | 需自行实现 | 内置支持 | 需改代码 |
+| 维护成本 | 中 | 低（社区维护） | 低 |
+| 适用场景 | 定制需求高 | 通用 | 单一渠道 |
 
 ---
 
-## 五、API 速查表
-
-### 短信 API（SMS4j）
-
-| 方法 | 说明 |
-|------|------|
-| `SmsFactory.getSmsBlend()` | 获取默认短信实例 |
-| `SmsFactory.getSmsBlend("config1")` | 获取指定配置短信实例 |
-| `smsBlend.sendMessage(phone, templateId, params)` | 发送模板短信 |
-| `smsBlend.sendMessage(phones, templateId, params)` | 批量发送 |
-| `response.isSuccess()` | 是否成功 |
-| `response.getMessage()` | 错误信息 |
-| `response.getBizId()` | 消息ID |
-
-### 邮件 API（MailUtils）
-
-| 方法 | 说明 |
-|------|------|
-| `MailUtils.sendText(to, subject, content)` | 文本邮件 |
-| `MailUtils.sendHtml(to, subject, content)` | HTML邮件 |
-| `MailUtils.sendText(to, subject, content, files...)` | 带附件文本邮件 |
-| `MailUtils.sendHtml(to, subject, content, files...)` | 带附件HTML邮件 |
-| `MailUtils.sendHtml(to, subject, content, imageMap)` | 带内嵌图片邮件 |
-| `MailUtils.send(to, cc, bcc, subject, content, isHtml)` | 抄送/密送 |
-| `MailUtils.sendHtml(tos, subject, content)` | 群发HTML邮件 |
-| `MailUtils.getMailAccount()` | 获取邮件配置 |
+## 常见错误
 
----
+```java
+// 1. 未配置就使用，NPE
+SmsSender sender = senderMap.get("xxx");
+sender.send(phone, template, params);  // sender 为 null -> NPE
+// 应先判空
+
+// 2. 模板参数名与模板定义不匹配
+params.put("verifyCode", "123456");  // 模板中变量名是 code
+// 应确认模板变量名
+
+// 3. 不检查发送结果
+smsService.send(phone, templateId, params);  // 发送可能失败
+// 应检查 SmsResult.isSuccess()
 
-## 六、核心文件位置
-
-| 类型 | 位置 |
-|------|------|
-| 短信配置 | `ruoyi-common/ruoyi-common-sms/.../config/SmsAutoConfiguration.java` |
-| 短信缓存 | `ruoyi-common/ruoyi-common-sms/.../core/dao/PlusSmsDao.java` |
-| 邮件工具类 | `ruoyi-common/ruoyi-common-mail/.../utils/MailUtils.java` |
-| 邮件配置 | `ruoyi-common/ruoyi-common-mail/.../config/MailConfig.java` |
-| 邮件属性 | `ruoyi-common/ruoyi-common-mail/.../config/properties/MailProperties.java` |
-| 验证码示例 | `ruoyi-admin/.../web/controller/CaptchaController.java` |
-| 短信演示 | `ruoyi-modules/ruoyi-demo/.../controller/SmsController.java` |
-| 工作流消息 | `ruoyi-modules/ruoyi-workflow/.../service/impl/FlwCommonServiceImpl.java` |
+// 4. 验证码无过期时间
+redisTemplate.opsForValue().set("sms:code:" + phone, code);  // 永不过期
+// 应设置 5-10 分钟过期
+
+// 5. 无限频控制（短信轰炸）
+// 应限制：同号码 60秒 1 次、每天最多 10 次
+
+// 6. 邮件密码用登录密码而非授权码
+// 大多数邮件服务商需要使用"授权码"而非"登录密码"
+
+// 7. 同步发送阻塞主线程
+// 短信/邮件发送应使用 @Async 异步执行
+```