ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/security-guard/references/encrypt-config.md

@@ -0,0 +1,103 @@
+# 数据加密详细配置
+
+## 加密配置（application.yml）
+
+```yaml
+mybatis-encryptor:
+  enable: true
+  algorithm: AES
+  password: your-aes-key-16bit    # AES 密钥（16/24/32位）
+  encode: BASE64
+  publicKey: xxx                  # RSA 公钥
+  privateKey: xxx                 # RSA 私钥
+```
+
+## EncryptUtils 工具类
+
+```java
+import org.dromara.common.encrypt.utils.EncryptUtils;
+
+// AES
+String encrypted = EncryptUtils.encryptByAes(data, aesKey);
+String decrypted = EncryptUtils.decryptByAes(encrypted, aesKey);
+
+// RSA（公钥加密，私钥解密）
+String encrypted = EncryptUtils.encryptByRsa(data, publicKey);
+String decrypted = EncryptUtils.decryptByRsa(encrypted, privateKey);
+
+// SM2 国密
+String encrypted = EncryptUtils.encryptBySm2(data, publicKey);
+String decrypted = EncryptUtils.decryptBySm2(encrypted, privateKey);
+
+// SM4 国密
+String encrypted = EncryptUtils.encryptBySm4(data, sm4Key);
+String decrypted = EncryptUtils.decryptBySm4(encrypted, sm4Key);
+
+// BASE64
+String encoded = EncryptUtils.encryptByBase64(data);
+String decoded = EncryptUtils.decryptByBase64(encoded);
+```
+
+## 字段加密完整示例
+
+```java
+import org.dromara.common.encrypt.annotation.EncryptField;
+import org.dromara.common.encrypt.enumd.AlgorithmType;
+import org.dromara.common.encrypt.enumd.EncodeType;
+
+public class User {
+    @EncryptField                                                          // 使用全局配置
+    private String password;
+
+    @EncryptField(algorithm = AlgorithmType.AES)                          // AES
+    private String idCard;
+
+    @EncryptField(algorithm = AlgorithmType.SM4)                          // SM4
+    private String phone;
+
+    @EncryptField(algorithm = AlgorithmType.AES, encode = EncodeType.HEX) // AES + HEX 编码
+    private String bankCard;
+}
+```
+
+## @RateLimiter 注解参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `key` | String | `""` | 限流 key，支持 SpEL |
+| `time` | int | `60` | 时间窗口（秒） |
+| `count` | int | `100` | 最大请求次数 |
+| `limitType` | LimitType | `DEFAULT` | 限流类型（DEFAULT/IP/CLUSTER） |
+| `message` | String | 国际化 key | 错误提示 |
+| `timeout` | int | `86400` | Redis 超时时间（秒） |
+
+## @RepeatSubmit 注解参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `interval` | int | `5000` | 间隔时间 |
+| `timeUnit` | TimeUnit | `MILLISECONDS` | 时间单位 |
+| `message` | String | 国际化 key | 错误提示 |
+
+## 文件上传安全模板
+
+```java
+private static final Set<String> ALLOWED_TYPES = Set.of(
+    "image/jpeg", "image/png", "image/gif", "image/webp"
+);
+private static final long MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+
+public void uploadFile(MultipartFile file) {
+    if (!ALLOWED_TYPES.contains(file.getContentType())) {
+        throw new ServiceException("不支持的文件类型");
+    }
+    if (file.getSize() > MAX_FILE_SIZE) {
+        throw new ServiceException("文件大小不能超过10MB");
+    }
+    String extension = getExtension(file.getOriginalFilename());
+    if (!Set.of(".jpg", ".jpeg", ".png", ".gif", ".webp").contains(extension.toLowerCase())) {
+        throw new ServiceException("不支持的文件扩展名");
+    }
+    String newName = UUID.randomUUID() + extension; // 重命名防路径穿越
+}
+```

package/src/skills/security-guard/references/sensitive-strategies.md

@@ -0,0 +1,42 @@
+# 数据脱敏策略完整列表（17种）
+
+> 来源：`ruoyi-common-sensitive/.../core/SensitiveStrategy`
+
+| 策略 | 枚举值 | 脱敏效果 | 说明 |
+|------|--------|---------|------|
+| 身份证 | `ID_CARD` | `110***********1234` | 保留前3位和后4位 |
+| 手机号 | `PHONE` | `138****8888` | 保留前3位和后4位 |
+| 邮箱 | `EMAIL` | `t**@example.com` | 保留用户名首尾和完整域名 |
+| 银行卡 | `BANK_CARD` | `6222***********1234` | 保留前4位和后4位 |
+| 中文姓名 | `CHINESE_NAME` | `张*` | 保留姓氏 |
+| 地址 | `ADDRESS` | `北京市朝阳区****` | 保留前8个字符 |
+| 固定电话 | `FIXED_PHONE` | `010****1234` | 保留区号和后4位 |
+| 密码 | `PASSWORD` | `******` | 全部掩码 |
+| IPv4 地址 | `IPV4` | `192.168.***.***` | 保留网络段 |
+| IPv6 地址 | `IPV6` | 部分隐藏 | 保留前缀 |
+| 车牌号 | `CAR_LICENSE` | `京A***12` | 支持普通和新能源 |
+| 用户ID | `USER_ID` | 随机数字 | 生成随机数字替代 |
+| 首字符保留 | `FIRST_MASK` | `张***` | 只显示第一个字符 |
+| 通用掩码 | `STRING_MASK` | `1234**7890` | 前4+4个*+后4 |
+| 高安全级别 | `MASK_HIGH_SECURITY` | `to******en` | 前2后2可见 |
+| 清空 | `CLEAR` | 空字符串 | 返回空字符串 |
+| 置空 | `CLEAR_TO_NULL` | `null` | 返回 null |
+
+## 用法示例
+
+```java
+@Sensitive(strategy = SensitiveStrategy.PHONE)
+private String phone;
+
+@Sensitive(strategy = SensitiveStrategy.ID_CARD)
+private String idCard;
+
+@Sensitive(strategy = SensitiveStrategy.ADDRESS)
+private String address;
+
+@Sensitive(strategy = SensitiveStrategy.IPV4)
+private String loginIp;
+
+@Sensitive(strategy = SensitiveStrategy.CAR_LICENSE)
+private String carNumber;
+```

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

@@ -0,0 +1,308 @@
+---
+name: sms-mail
+description: |
+  当需要发送短信、邮件通知时自动使用此 Skill。
+
+  触发场景：
+  - 需要发送短信验证码
+  - 需要发送邮件通知（文本/HTML）
+  - 需要配置短信服务商（阿里云/腾讯云/华为云等）
+  - 需要配置邮件服务器（SMTP）
+  - 需要实现多渠道消息通知
+
+  触发词：短信、邮件、SMS、验证码、通知、SMS4j、MailUtils、邮件发送、短信发送、SmsBlend、SmsFactory、SMTP、模板消息
+---
+
+# 短信与邮件开发指南
+
+> 短信模块：`ruoyi-common/ruoyi-common-sms`（SMS4j）
+> 邮件模块：`ruoyi-common/ruoyi-common-mail`（Hutool JakartaMail）
+
+---
+
+## 一、短信开发（SMS4j）
+
+### 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());
+}
+```
+
+### 1.3 验证码短信示例
+
+```java
+@RestController
+@RequestMapping("/captcha")
+@RequiredArgsConstructor
+public class CaptchaController {
+
+    @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);
+
+        if (!smsResponse.isSuccess()) {
+            log.error("短信发送失败：{}", smsResponse.getMessage());
+            return R.fail("短信发送失败");
+        }
+        return R.ok("验证码已发送");
+    }
+
+    @PostMapping("/verify")
+    public R<Boolean> verifySmsCode(@RequestParam String phonenumber,
+                                     @RequestParam String code) {
+        String cacheKey = "sms:code:" + phonenumber;
+        String cachedCode = RedisUtils.getCacheObject(cacheKey);
+
+        if (cachedCode == null) return R.fail("验证码已过期");
+        if (!cachedCode.equals(code)) return R.fail("验证码错误");
+
+        RedisUtils.deleteObject(cacheKey);
+        return R.ok(true);
+    }
+}
+```
+
+---
+
+## 二、邮件开发（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
+```
+
+> 常用 SMTP 服务器配置详见 [references/mail-config.md](references/mail-config.md)
+
+### 2.2 核心 API
+
+```java
+import org.dromara.common.mail.utils.MailUtils;
+
+// 发送文本邮件
+String msgId = MailUtils.sendText("to@example.com", "标题", "正文内容");
+
+// 发送HTML邮件
+String msgId = MailUtils.sendHtml("to@example.com", "标题", "<h1>内容</h1>");
+
+// 带附件
+String msgId = MailUtils.sendText("to@example.com", "标题", "正文", attachment);
+String msgId = MailUtils.sendHtml("to@example.com", "标题", htmlContent, attachment);
+
+// 带内嵌图片
+Map<String, InputStream> imageMap = Map.of("logo", new FileInputStream("logo.png"));
+String msgId = MailUtils.sendHtml("to@example.com", "标题",
+    "<img src='cid:logo'/>", imageMap);
+
+// 群发
+String msgId = MailUtils.sendHtml(List.of("a@x.com", "b@x.com"), "标题", htmlContent);
+
+// 抄送/密送
+String msgId = MailUtils.send("to@x.com", "cc@x.com", "bcc@x.com", "标题", "内容", true);
+
+// 获取邮件账户配置
+MailAccount account = MailUtils.getMailAccount();
+```
+
+### 2.3 邮件验证码示例
+
+```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 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;
+        }
+        return false;
+    }
+}
+```
+
+---
+
+## 三、多渠道消息通知示例
+
+```java
+@Service
+@RequiredArgsConstructor
+public class MessageService {
+
+    public void sendMessage(List<String> messageType, String subject,
+                           String message, List<UserDTO> userList) {
+        for (UserDTO user : userList) {
+            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 (messageType.contains("email") && StringUtils.isNotBlank(user.getEmail())) {
+                    MailUtils.sendHtml(user.getEmail(), subject,
+                        "<div style='padding:20px;'><h3>" + subject + "</h3><p>" + message + "</p></div>");
+                }
+            } catch (Exception e) {
+                log.error("消息发送失败，类型：{}，用户：{}，错误：{}",
+                    messageType, user.getUserId(), e.getMessage());
+            }
+        }
+    }
+}
+```
+
+---
+
+## 四、常见错误
+
+```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));
+```
+
+---
+
+## 五、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()` | 获取邮件配置 |
+
+---
+
+## 六、核心文件位置
+
+| 类型 | 位置 |
+|------|------|
+| 短信配置 | `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` |

package/src/skills/sms-mail/references/mail-config.md

@@ -0,0 +1,88 @@
+# 邮件完整配置参考
+
+## 常用 SMTP 服务器
+
+| 邮箱服务商 | SMTP 服务器 | SSL 端口 | 非 SSL 端口 |
+|-----------|-------------|---------|------------|
+| 163 邮箱 | smtp.163.com | 465 | 25 |
+| QQ 邮箱 | smtp.qq.com | 465 | 587 |
+| 阿里企业邮箱 | smtp.mxhichina.com | 465 | 25 |
+| 腾讯企业邮箱 | smtp.exmail.qq.com | 465 | 587 |
+| Gmail | smtp.gmail.com | 465 | 587 |
+| Outlook | smtp.office365.com | 587 | 587 |
+
+## 完整配置示例
+
+```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
+```
+
+## 业务通知邮件示例
+
+### 订单确认邮件
+
+```java
+public void sendOrderConfirmation(Order order, User user) {
+    String htmlContent = String.format("""
+        <div style="max-width: 600px; margin: 0 auto; font-family: Arial;">
+            <h2>订单确认</h2>
+            <p>尊敬的 %s，您好！</p>
+            <table style="width: 100%%; border-collapse: collapse;">
+                <tr><td>订单号：</td><td>%s</td></tr>
+                <tr><td>下单时间：</td><td>%s</td></tr>
+                <tr><td>订单金额：</td><td>￥%s</td></tr>
+            </table>
+        </div>
+        """,
+        user.getNickName(), order.getOrderNo(),
+        DateUtils.parseDateToStr("yyyy-MM-dd HH:mm:ss", order.getCreateTime()),
+        order.getTotalAmount()
+    );
+
+    MailUtils.sendHtml(user.getEmail(), "【若依商城】订单确认", htmlContent);
+}
+```
+
+### 密码重置邮件
+
+```java
+public void sendPasswordResetEmail(String email, String resetToken) {
+    String resetUrl = "https://example.com/reset-password?token=" + resetToken;
+    String htmlContent = String.format("""
+        <div style="padding: 20px;">
+            <h2>密码重置</h2>
+            <p><a href="%s" style="color: #1890ff;">点击重置密码</a></p>
+            <p>链接有效期30分钟。</p>
+        </div>
+        """, resetUrl);
+
+    MailUtils.sendHtml(email, "【若依系统】密码重置", htmlContent);
+}
+```
+
+### 报表邮件（带附件）
+
+```java
+public void sendReportEmail(String email, String reportName, File reportFile) {
+    String htmlContent = String.format("""
+        <div style="padding: 20px;">
+            <h2>%s</h2>
+            <p>请查看附件中的报表文件。</p>
+            <p>生成时间：%s</p>
+        </div>
+        """, reportName, DateUtils.getTime());
+
+    MailUtils.sendHtml(email, reportName, htmlContent, reportFile);
+}
+```

package/src/skills/sms-mail/references/sms-config.md

@@ -0,0 +1,74 @@
+# 短信完整配置参考
+
+## 支持的服务商
+
+| 服务商 | 配置标识 | 说明 |
+|--------|---------|------|
+| 阿里云 | `alibaba` | 阿里云短信服务 |
+| 腾讯云 | `tencent` | 腾讯云短信（需 sdk-app-id） |
+| 华为云 | `huawei` | 华为云短信 |
+| 云片 | `yunpian` | 云片短信 |
+| 合一 | `unisms` | 合一短信 |
+| 京东云 | `jdcloud` | 京东云短信 |
+| 容联云 | `cloopen` | 容联云通讯 |
+| 亿美软通 | `emay` | 亿美短信 |
+| 天翼云 | `ctyun` | 天翼云短信 |
+
+## 完整配置示例
+
+```yaml
+sms:
+  config-type: yaml
+  # 短信拦截配置（可选）
+  restricted:
+    account-max: 0              # 是否开启账号维度每日上限
+    minute-max: 1               # 是否开启手机号维度每分钟上限
+    account-max-count: 10       # 单账号每日上限
+    minute-max-count: 1         # 单手机号每分钟上限
+
+  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"
+```
+
+## 业务通知短信示例
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderNotifyService {
+
+    public void notifyShipment(Order order) {
+        Map<String, String> params = new LinkedHashMap<>();
+        params.put("orderNo", order.getOrderNo());
+        params.put("expressNo", order.getExpressNo());
+        params.put("expressCompany", order.getExpressCompany());
+
+        SmsBlend smsBlend = SmsFactory.getSmsBlend("config1");
+        SmsResponse response = smsBlend.sendMessage(
+            order.getPhone(), "SMS_SHIPMENT_NOTIFY", params);
+
+        if (!response.isSuccess()) {
+            log.error("发货通知短信发送失败，订单号：{}，错误：{}",
+                order.getOrderNo(), response.getMessage());
+        }
+    }
+
+    public void sendMarketingSms(List<String> phones, String content) {
+        Map<String, String> params = new LinkedHashMap<>();
+        params.put("content", content);
+
+        SmsFactory.getSmsBlend("config1").sendMessage(phones, "SMS_MARKETING", params);
+    }
+}
+```