leniu-dev 2.0.0

package/.codex/skills/scheduled-jobs/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: scheduled-jobs
+description: |
+  通用定时任务开发指南。涵盖 @Scheduled、Quartz、XXL-Job 等方案的概念对比与实现模式。
+  触发场景：
+  - 每日数据汇总、定期清理等周期性任务
+  - 分布式任务调度、失败重试
+  - 任务分片、广播任务
+  - 可视化任务管理和监控
+  触发词：定时任务、任务调度、@Scheduled、Quartz、XXL-Job、Cron、重试、分片任务、广播任务、分布式任务
+  注意：如果项目有专属技能（如 `leniu-java-task`），优先使用专属版本。
+---
+
+# 定时任务开发指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-java-task`），优先使用。
+
+## 设计原则
+
+1. **幂等性**：任务重复执行不会产生副作用。考虑任务被重试、多次调度的情况。
+2. **可观测**：任务执行结果必须可追踪（日志、监控、告警）。
+3. **故障隔离**：单个任务失败不应影响其他任务的调度。
+4. **超时控制**：设置合理的执行超时时间，避免任务无限阻塞。
+
+---
+
+## 方案对比
+
+| 维度 | @Scheduled | Quartz | XXL-Job | 其他（SnailJob 等） |
+|------|-----------|--------|---------|-------------------|
+| 学习成本 | 极低 | 中等 | 低 | 低-中 |
+| 分布式支持 | 无 | 支持（数据库锁） | 原生支持 | 原生支持 |
+| 可视化管理 | 无 | 无（需自建） | Web 控制台 | Web 控制台 |
+| 失败重试 | 无 | 支持 | 支持 | 支持 |
+| 任务分片 | 不支持 | 不支持 | 支持 | 支持 |
+| 广播模式 | 不支持 | 不支持 | 支持 | 支持 |
+| 工作流编排 | 不支持 | 不支持 | 子任务依赖 | 部分支持 |
+| 依赖 | Spring 内置 | quartz jar | 独立服务 | 独立服务 |
+| 适用场景 | 简单周期任务 | 中等复杂度 | 生产级分布式 | 生产级分布式 |
+
+### 选型决策树
+
+```
+需要分布式调度？
+├── 否 → @Scheduled（简单定时）
+└── 是 → 需要可视化管理？
+        ├── 否 → Quartz + 数据库（中等规模）
+        └── 是 → XXL-Job / SnailJob / PowerJob（生产推荐）
+```
+
+---
+
+## 实现模式
+
+### 方案一：@Scheduled（Spring 内置）
+
+```java
+@Component
+@EnableScheduling
+public class SimpleScheduledTasks {
+
+    // 固定频率：每30秒执行一次
+    @Scheduled(fixedRate = 30000)
+    public void heartbeat() {
+        log.info("心跳检测");
+    }
+
+    // 固定延迟：上次执行完成后等10秒再执行
+    @Scheduled(fixedDelay = 10000)
+    public void cleanTempFiles() {
+        log.info("清理临时文件");
+    }
+
+    // Cron 表达式：每天凌晨2点执行
+    @Scheduled(cron = "0 0 2 * * ?")
+    public void dailyReport() {
+        log.info("生成日报");
+    }
+
+    // 使用配置文件中的 Cron
+    @Scheduled(cron = "${task.cleanup.cron:0 0 3 * * ?}")
+    public void configuredTask() {
+        log.info("可配置的定时任务");
+    }
+}
+```
+
+**注意事项**：
+- 默认单线程执行，需配置线程池避免任务阻塞
+- 多实例部署时每个实例都会执行，需分布式锁控制
+
+```java
+@Configuration
+public class SchedulingConfig implements SchedulingConfigurer {
+    @Override
+    public void configureTasks(ScheduledTaskRegistrar registrar) {
+        registrar.setScheduler(Executors.newScheduledThreadPool(5));
+    }
+}
+```
+
+### 方案二：Quartz
+
+```java
+// 1. 定义 Job
+public class OrderCleanupJob implements Job {
+    @Override
+    public void execute(JobExecutionContext context) throws JobExecutionException {
+        JobDataMap dataMap = context.getMergedJobDataMap();
+        int days = dataMap.getInt("retentionDays");
+        // 业务逻辑...
+    }
+}
+
+// 2. 配置调度
+@Configuration
+public class QuartzConfig {
+
+    @Bean
+    public JobDetail orderCleanupJobDetail() {
+        return JobBuilder.newJob(OrderCleanupJob.class)
+            .withIdentity("orderCleanup", "maintenance")
+            .usingJobData("retentionDays", 30)
+            .storeDurably()
+            .build();
+    }
+
+    @Bean
+    public Trigger orderCleanupTrigger() {
+        return TriggerBuilder.newTrigger()
+            .forJob(orderCleanupJobDetail())
+            .withIdentity("orderCleanupTrigger", "maintenance")
+            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 2 * * ?"))
+            .build();
+    }
+}
+```
+
+### 方案三：分布式任务调度平台（XXL-Job 等）
+
+```java
+// 通用模式：注解标记任务处理器
+@Component
+public class OrderCleanupJobHandler {
+
+    @Autowired
+    private OrderService orderService;
+
+    // 具体注解取决于所选平台
+    // XXL-Job: @XxlJob("orderCleanupHandler")
+    // SnailJob: @JobExecutor(name = "orderCleanupJob")
+    public void execute(String params) {
+        log.info("开始清理过期订单");
+        try {
+            int days = StringUtils.isBlank(params) ? 30 : Integer.parseInt(params);
+            int count = orderService.cleanupExpiredOrders(days);
+            log.info("清理完成，删除 {} 条", count);
+        } catch (Exception e) {
+            log.error("清理失败: {}", e.getMessage());
+            throw e;  // 抛出异常触发平台重试
+        }
+    }
+}
+```
+
+### 执行模式
+
+| 模式 | 特点 | 适用场景 |
+|------|------|---------|
+| **集群/随机** | 多节点竞争，只有一个执行 | 订单处理、数据汇总 |
+| **广播** | 所有节点都执行 | 清理本地缓存、刷新配置 |
+| **分片** | 按规则分片，每节点处理部分数据 | 大数据量批处理 |
+| **MapReduce** | 动态分片 + 结果汇总 | 分布式计算、统计 |
+
+---
+
+## 最佳实践
+
+### 标准任务模板
+
+```java
+@Component
+public class [你的任务类] {
+
+    private static final Logger log = LoggerFactory.getLogger([你的任务类].class);
+
+    @Autowired
+    private [你的业务Service] bizService;
+
+    public void execute(String params) {
+        long startTime = System.currentTimeMillis();
+        log.info("[任务开始] 参数: {}", params);
+
+        try {
+            // 1. 解析参数
+            int days = parseParams(params);
+
+            // 2. 幂等检查
+            if (bizService.isAlreadyProcessed(today())) {
+                log.info("[任务跳过] 今日已执行");
+                return;
+            }
+
+            // 3. 执行业务逻辑
+            int count = bizService.process(days);
+
+            // 4. 记录结果
+            long cost = System.currentTimeMillis() - startTime;
+            log.info("[任务完成] 处理 {} 条，耗时 {} ms", count, cost);
+
+        } catch (Exception e) {
+            log.error("[任务失败] {}", e.getMessage(), e);
+            throw e;  // 抛出异常触发重试
+        }
+    }
+}
+```
+
+### 重试策略对比
+
+| 策略 | 说明 | 适用场景 |
+|------|------|---------|
+| 固定间隔 | 每次间隔相同（如 30s） | 网络抖动、临时故障 |
+| 指数退避 | 间隔逐倍增加（1s, 2s, 4s, 8s...） | 服务恢复中 |
+| Cron 重试 | 按 Cron 表达式重试 | 定点重试 |
+| 最大次数 | 限制最大重试次数 | 防止无限重试 |
+
+### Cron 表达式速查
+
+| 表达式 | 含义 |
+|--------|------|
+| `0 0 2 * * ?` | 每天凌晨 2:00 |
+| `0 0/30 * * * ?` | 每 30 分钟 |
+| `0 0 9-18 * * MON-FRI` | 工作日 9-18 点每小时 |
+| `0 0 0 1 * ?` | 每月 1 号零点 |
+| `0 0 0 L * ?` | 每月最后一天零点 |
+
+---
+
+## 常见错误
+
+```java
+// 1. @Scheduled 任务中抛出异常但不处理
+@Scheduled(fixedRate = 60000)
+public void task() {
+    service.process();  // 异常后任务停止调度！
+}
+// 应捕获异常
+@Scheduled(fixedRate = 60000)
+public void task() {
+    try {
+        service.process();
+    } catch (Exception e) {
+        log.error("任务执行失败", e);
+    }
+}
+
+// 2. @Scheduled 默认单线程，长任务阻塞其他任务
+// 应配置线程池（见上文 SchedulingConfig）
+
+// 3. 多实例部署未做互斥
+// @Scheduled 每个实例都执行 -> 数据重复处理
+// 应使用分布式锁（Redis / 数据库）或分布式调度平台
+
+// 4. 任务非幂等
+public void syncData() {
+    insertAll(fetchData());  // 重复执行会插入重复数据
+}
+// 应先检查是否已处理
+
+// 5. 任务内开启大事务
+@Transactional
+public void processAllOrders() {
+    // 处理百万条数据在一个事务中 -> 内存溢出、锁超时
+}
+// 应分批处理，每批独立事务
+```

package/.codex/skills/security-guard/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: security-guard
+description: |
+  通用后端安全开发指南。包含认证授权模式对比、输入校验、XSS/SQL注入防护、数据脱敏加密、安全检查清单。
+  触发场景：
+  - 设计认证授权方案
+  - 配置权限校验
+  - 防护 XSS / SQL 注入
+  - 数据脱敏 / 加密处理
+  - 安全合规审查
+  触发词：安全、认证、授权、权限、Token、登录、XSS、SQL注入、脱敏、加密、RBAC、OAuth、CORS、漏洞防护
+  注意：如果项目有专属技能（如 `leniu-security-guard`），优先使用专属版本。
+---
+
+# 安全开发指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-security-guard`），优先使用。
+
+## 设计原则
+
+1. **纵深防御**：不依赖单一安全机制，从传输层、认证层、授权层、数据层多维度防护。
+2. **最小权限**：默认拒绝，显式授权。每个接口必须声明所需权限。
+3. **输入不可信**：所有外部输入（用户参数、请求头、Cookie）必须校验后使用。
+4. **敏感数据保护**：存储加密、传输加密、展示脱敏，三层保护。
+5. **审计可追溯**：关键操作记录日志，包含操作人、操作时间、操作内容。
+
+---
+
+## 认证授权方案对比
+
+| 维度 | Spring Security | Apache Shiro | Sa-Token |
+|------|----------------|-------------|----------|
+| 学习曲线 | 陡峭 | 中等 | 平缓 |
+| 功能丰富度 | 最全面 | 基础够用 | 功能丰富 |
+| Spring 集成 | 原生集成 | 需适配 | 自动配置 |
+| OAuth2 支持 | 原生支持 | 需扩展 | 内置 SSO |
+| 微服务支持 | 优秀 | 一般 | 良好 |
+| 适用场景 | 企业级、复杂权限 | 轻量项目 | 快速开发 |
+
+---
+
+## 实现模式
+
+### 1. 认证（Authentication）
+
+```java
+// 方式一：注解式认证（框架无关的概念）
+@[你的认证注解]                          // 登录校验
+@[你的权限注解]("system:user:add")       // 权限校验
+@[你的角色注解]("admin")                 // 角色校验
+
+// 方式二：编程式认证
+@RestController
+public class UserController {
+
+    @Autowired
+    private [你的安全工具类] securityUtils;
+
+    @GetMapping("/profile")
+    public Result<?> profile() {
+        // 获取当前登录用户
+        Long userId = securityUtils.getCurrentUserId();
+        String username = securityUtils.getCurrentUsername();
+        boolean isAdmin = securityUtils.hasRole("admin");
+        boolean hasPerm = securityUtils.hasPermission("system:user:list");
+
+        if (!securityUtils.isAuthenticated()) {
+            throw new [你的异常类]("未登录");
+        }
+        // ...
+    }
+}
+```
+
+### 2. 授权模型（RBAC）
+
+```
+用户 (User)
+  └── 角色 (Role)         -- 多对多
+        └── 权限 (Permission) -- 多对多
+              └── 菜单/按钮/API
+
+权限标识格式：模块:资源:操作
+示例：system:user:add, order:info:export
+```
+
+```java
+// 多权限校验（满足其一 / 全部满足）
+@RequiresPermissions(value = {"system:user:add", "system:user:edit"}, logical = Logical.OR)
+@RequiresPermissions(value = {"system:user:add", "system:user:edit"}, logical = Logical.AND)
+
+// 多角色校验
+@RequiresRoles(value = {"admin", "editor"}, logical = Logical.OR)
+```
+
+### 3. 输入校验
+
+```java
+public class UserDTO {
+    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
+    private Long id;
+
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 2, max = 20, message = "用户名长度2-20")
+    @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "只能包含字母数字下划线")
+    private String username;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    @Min(value = 0, message = "年龄不能为负")
+    @Max(value = 150, message = "年龄超出范围")
+    private Integer age;
+}
+
+// Controller 分组校验
+@PostMapping
+public Result<?> add(@Validated(AddGroup.class) @RequestBody UserDTO dto) { }
+
+@PutMapping
+public Result<?> update(@Validated(UpdateGroup.class) @RequestBody UserDTO dto) { }
+```
+
+### 4. 越权访问防护
+
+```java
+public [你的VO类] selectById(Long id) {
+    var entity = baseMapper.selectById(id);
+    if (entity == null) {
+        throw new [你的异常类]("数据不存在");
+    }
+    // 非管理员只能访问自己的数据
+    Long currentUserId = [你的安全工具类].getCurrentUserId();
+    if (![你的安全工具类].isAdmin() && !entity.getCreatedBy().equals(currentUserId)) {
+        throw new [你的异常类]("无权访问此数据");
+    }
+    return convertToVo(entity);
+}
+```
+
+---
+
+## 常见漏洞防护
+
+### SQL 注入
+
+```java
+// 禁止：字符串拼接 SQL
+"SELECT * FROM user WHERE name = '" + name + "'"
+@Select("SELECT * FROM user WHERE name = '${name}'")
+
+// 正确：参数化查询
+@Select("SELECT * FROM user WHERE name = #{name}")
+// 或使用 ORM 框架的 QueryWrapper / LambdaQueryWrapper
+```
+
+### XSS 防护
+
+```java
+// 方式一：全局 Filter（推荐）
+@Bean
+public FilterRegistrationBean<XssFilter> xssFilter() {
+    FilterRegistrationBean<XssFilter> registration = new FilterRegistrationBean<>();
+    registration.setFilter(new XssFilter());
+    registration.addUrlPatterns("/*");
+    registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
+    return registration;
+}
+
+// 方式二：手动转义
+String safe = HtmlUtils.htmlEscape(userInput);
+String safe = StringEscapeUtils.escapeHtml4(userInput);
+```
+
+### 敏感信息泄露
+
+```java
+// 禁止：直接返回 Entity（可能包含密码等）
+return userDao.getById(id);
+
+// 正确：使用 VO 过滤 + @Sensitive 脱敏
+UserVo vo = new UserVo();
+BeanUtils.copyProperties(user, vo);
+return vo;
+
+// 日志脱敏
+log.info("手机号: {}", DesensitizedUtil.mobilePhone(phone));
+```
+
+---
+
+## 安全检查清单
+
+### 代码审查
+
+- [ ] 用户输入经过 `@NotBlank` / `@Size` / `@Pattern` 校验
+- [ ] SQL 使用参数化查询（`#{}` 而非 `${}`）
+- [ ] 敏感字段使用脱敏注解或 VO 过滤
+- [ ] 存储敏感数据使用加密
+- [ ] Controller 添加权限注解
+- [ ] 写入接口添加防重复提交
+- [ ] 高频接口添加限流
+- [ ] 批量操作校验数据归属（防越权）
+- [ ] 文件上传校验类型 / 大小 / 扩展名（白名单）
+- [ ] 日志中无敏感信息（或已脱敏）
+
+### 配置与部署
+
+- [ ] 生产环境关闭调试模式、Swagger
+- [ ] 敏感配置使用环境变量或配置中心加密
+- [ ] Token 有效期合理（2-24h）
+- [ ] CORS 不使用 `*`，限定域名
+- [ ] 启用 HTTPS
+- [ ] 设置安全响应头（X-Frame-Options、X-Content-Type-Options、CSP）
+- [ ] 错误页不泄露堆栈信息
+- [ ] 数据库 / Redis 端口不对外暴露
+
+---
+
+## 常见错误
+
+```java
+// 1. 忘记加认证注解，接口裸奔
+@GetMapping("/users")
+public Result<?> list() { ... }  // 任何人可访问！
+
+// 2. 只校验前端，不校验后端
+// 前端限制了输入范围，但后端不做校验 -> 可被绕过
+
+// 3. 用 Map 传递用户信息（类型不安全）
+Map<String, Object> user = getCurrentUser();  // 缺乏类型约束
+// 应使用强类型 LoginUser 对象
+
+// 4. 密码明文存储
+user.setPassword(rawPassword);
+// 应使用 BCrypt / SCrypt 哈希
+user.setPassword(passwordEncoder.encode(rawPassword));
+
+// 5. Token 存储敏感信息
+// JWT payload 不应包含密码、完整身份证号等
+
+// 6. CORS 配置过于宽松
+.allowedOrigins("*").allowedMethods("*").allowCredentials(true)
+// allowedOrigins("*") 与 allowCredentials(true) 不能同时使用
+```

package/.codex/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/.codex/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;
+```