ai-engineering-init 1.7.0 → 1.10.0

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

@@ -1,224 +1,176 @@
 ---
 name: scheduled-jobs
 description: |
-  定时任务开发指南。涵盖 @Scheduled、SnailJob 两种方案，支持分布式任务调度、失败重试、工作流编排。
-
+  通用定时任务开发指南。涵盖 @Scheduled、Quartz、XXL-Job 等方案的概念对比与实现模式。
   触发场景：
   - 每日数据汇总、定期清理等周期性任务
-  - 分布式复杂业务、失败重试、可视化管理（SnailJob）
-  - 任务分片、Map/MapReduce 分布式计算
-  - 广播任务（所有节点执行）
-
-  触发词：定时任务、SnailJob、任务调度、重试机制、工作流、@JobExecutor、@Scheduled、分布式任务、广播任务、分片任务、MapReduce
-
-  核心特性：
-  - @Scheduled：简单周期任务、框架内置
-  - SnailJob：分布式集群、可视化管理、失败重试、工作流编排
+  - 分布式任务调度、失败重试
+  - 任务分片、广播任务
+  - 可视化任务管理和监控
+  触发词：定时任务、任务调度、@Scheduled、Quartz、XXL-Job、Cron、重试、分片任务、广播任务、分布式任务
+  注意：如果项目有专属技能（如 `leniu-java-task`），优先使用专属版本。
 ---
 
 # 定时任务开发指南
 
-> 模块位置：`ruoyi-modules/ruoyi-job`
+> 通用模板。如果项目有专属技能（如 `leniu-java-task`），优先使用。
 
-## 方案选择
+## 设计原则
 
-| 场景 | 推荐 | 理由 |
-|------|------|------|
-| 简单周期任务（日报、清理） | `@Scheduled` | 内置、无依赖 |
-| 分布式/需重试/需监控 | **SnailJob** | 可视化管理、完整重试 |
-| 广播（所有节点执行） | **SnailJob** | 支持广播模式 |
-| 海量数据分片 | **SnailJob** | 静态分片/Map/MapReduce |
+1. **幂等性**：任务重复执行不会产生副作用。考虑任务被重试、多次调度的情况。
+2. **可观测**：任务执行结果必须可追踪（日志、监控、告警）。
+3. **故障隔离**：单个任务失败不应影响其他任务的调度。
+4. **超时控制**：设置合理的执行超时时间，避免任务无限阻塞。
 
 ---
 
-## SnailJob 配置
-
-```yaml
-# application-dev.yml
-snail-job:
-  enabled: ${SNAIL_JOB_ENABLED:false}
-  group: ${app.id}
-  token: ${SNAIL_JOB_TOKEN:SJ_cKqBTPzCsWA3VyuCfFoccmuIEGXjr5KT}
-  server:
-    host: ${SNAIL_JOB_HOST:127.0.0.1}
-    port: ${SNAIL_JOB_PORT:17888}
-  namespace: ${spring.profiles.active}
-  port: 2${server.port}
-```
+## 方案对比
 
-```java
-// ruoyi-common/ruoyi-common-job/.../config/SnailJobConfig.java
-@AutoConfiguration
-@ConditionalOnProperty(prefix = "snail-job", name = "enabled", havingValue = "true")
-@EnableScheduling
-@EnableSnailJob
-public class SnailJobConfig {}
+| 维度 | @Scheduled | Quartz | XXL-Job | 其他（SnailJob 等） |
+|------|-----------|--------|---------|-------------------|
+| 学习成本 | 极低 | 中等 | 低 | 低-中 |
+| 分布式支持 | 无 | 支持（数据库锁） | 原生支持 | 原生支持 |
+| 可视化管理 | 无 | 无（需自建） | Web 控制台 | Web 控制台 |
+| 失败重试 | 无 | 支持 | 支持 | 支持 |
+| 任务分片 | 不支持 | 不支持 | 支持 | 支持 |
+| 广播模式 | 不支持 | 不支持 | 支持 | 支持 |
+| 工作流编排 | 不支持 | 不支持 | 子任务依赖 | 部分支持 |
+| 依赖 | Spring 内置 | quartz jar | 独立服务 | 独立服务 |
+| 适用场景 | 简单周期任务 | 中等复杂度 | 生产级分布式 | 生产级分布式 |
+
+### 选型决策树
+
+```
+需要分布式调度？
+├── 否 → @Scheduled（简单定时）
+└── 是 → 需要可视化管理？
+        ├── 否 → Quartz + 数据库（中等规模）
+        └── 是 → XXL-Job / SnailJob / PowerJob（生产推荐）
 ```
 
 ---
 
-## SnailJob 任务类型
+## 实现模式
 
-### 基础任务（注解方式，推荐）
-
-> 源码：`ruoyi-job/.../snailjob/TestAnnoJobExecutor.java`
+### 方案一：@Scheduled（Spring 内置）
 
 ```java
-import com.aizuda.snailjob.client.job.core.annotation.JobExecutor;
-import com.aizuda.snailjob.client.job.core.dto.JobArgs;
-import com.aizuda.snailjob.model.dto.ExecuteResult;
-import com.aizuda.snailjob.common.log.SnailJobLog;
-import com.aizuda.snailjob.common.core.util.JsonUtil;
-
 @Component
-@JobExecutor(name = "testJobExecutor")
-public class TestAnnoJobExecutor {
+@EnableScheduling
+public class SimpleScheduledTasks {
 
-    public ExecuteResult jobExecute(JobArgs jobArgs) {
-        SnailJobLog.REMOTE.info("任务执行，参数: {}", JsonUtil.toJsonString(jobArgs));
-        String jobParams = jobArgs.getJobParams();
-        // 业务逻辑...
-        return ExecuteResult.success("执行成功");
+    // 固定频率：每30秒执行一次
+    @Scheduled(fixedRate = 30000)
+    public void heartbeat() {
+        log.info("心跳检测");
     }
-}
-```
-
-### 广播任务
 
-> 源码：`ruoyi-job/.../snailjob/TestBroadcastJob.java`
-
-所有节点都执行，适用于清理本地缓存等场景。
+    // 固定延迟：上次执行完成后等10秒再执行
+    @Scheduled(fixedDelay = 10000)
+    public void cleanTempFiles() {
+        log.info("清理临时文件");
+    }
 
-```java
-@Component
-@JobExecutor(name = "testBroadcastJob")
-public class TestBroadcastJob {
+    // Cron 表达式：每天凌晨2点执行
+    @Scheduled(cron = "0 0 2 * * ?")
+    public void dailyReport() {
+        log.info("生成日报");
+    }
 
-    public ExecuteResult jobExecute(JobArgs jobArgs) {
-        SnailJobLog.REMOTE.info("广播任务执行");
-        // 每个节点都会执行此方法
-        return ExecuteResult.success("广播任务执行成功");
+    // 使用配置文件中的 Cron
+    @Scheduled(cron = "${task.cleanup.cron:0 0 3 * * ?}")
+    public void configuredTask() {
+        log.info("可配置的定时任务");
     }
 }
 ```
 
-### 静态分片任务
-
-> 源码：`ruoyi-job/.../snailjob/TestStaticShardingJob.java`
-
-按固定规则分片，每个节点处理不同数据范围。
+**注意事项**：
+- 默认单线程执行，需配置线程池避免任务阻塞
+- 多实例部署时每个实例都会执行，需分布式锁控制
 
 ```java
-@Component
-@JobExecutor(name = "testStaticShardingJob")
-public class TestStaticShardingJob {
-
-    // jobParams 格式：起始ID,结束ID（如：1,100000）
-    public ExecuteResult jobExecute(JobArgs jobArgs) {
-        String[] split = jobArgs.getJobParams().split(",");
-        Long fromId = Long.parseLong(split[0]);
-        Long toId = Long.parseLong(split[1]);
-        SnailJobLog.REMOTE.info("处理 ID 范围: {} - {}", fromId, toId);
-        // 处理该范围的数据
-        return ExecuteResult.success("分片任务完成");
+@Configuration
+public class SchedulingConfig implements SchedulingConfigurer {
+    @Override
+    public void configureTasks(ScheduledTaskRegistrar registrar) {
+        registrar.setScheduler(Executors.newScheduledThreadPool(5));
     }
 }
 ```
 
-**控制台分片配置**：分片0=`1,100000` / 分片1=`100001,200000` / 分片2=`200001,300000`
-
-### Map 任务（动态分片）
-
-> 源码：`ruoyi-job/.../snailjob/TestMapJobAnnotation.java`
-
-运行时动态拆分数据，并行执行。
+### 方案二：Quartz
 
 ```java
-import com.aizuda.snailjob.client.job.core.annotation.MapExecutor;
-import com.aizuda.snailjob.client.job.core.dto.MapArgs;
-import com.aizuda.snailjob.client.job.core.MapHandler;
+// 1. 定义 Job
+public class OrderCleanupJob implements Job {
+    @Override
+    public void execute(JobExecutionContext context) throws JobExecutionException {
+        JobDataMap dataMap = context.getMergedJobDataMap();
+        int days = dataMap.getInt("retentionDays");
+        // 业务逻辑...
+    }
+}
 
-@Component
-@JobExecutor(name = "testMapJobAnnotation")
-public class TestMapJobAnnotation {
-
-    @MapExecutor  // 无 taskName = 入口方法
-    public ExecuteResult doJobMapExecute(MapArgs mapArgs, MapHandler mapHandler) {
-        List<List<Integer>> partition = IntStream.rangeClosed(1, 200)
-            .boxed()
-            .collect(Collectors.groupingBy(i -> (i - 1) / 50))
-            .values().stream().toList();
-        return mapHandler.doMap(partition, "doCalc");
+// 2. 配置调度
+@Configuration
+public class QuartzConfig {
+
+    @Bean
+    public JobDetail orderCleanupJobDetail() {
+        return JobBuilder.newJob(OrderCleanupJob.class)
+            .withIdentity("orderCleanup", "maintenance")
+            .usingJobData("retentionDays", 30)
+            .storeDurably()
+            .build();
     }
 
-    @MapExecutor(taskName = "doCalc")  // 子任务
-    public ExecuteResult doCalc(MapArgs mapArgs) {
-        List<Integer> sourceList = (List<Integer>) mapArgs.getMapResult();
-        int total = sourceList.stream().mapToInt(i -> i).sum();
-        return ExecuteResult.success(total);
+    @Bean
+    public Trigger orderCleanupTrigger() {
+        return TriggerBuilder.newTrigger()
+            .forJob(orderCleanupJobDetail())
+            .withIdentity("orderCleanupTrigger", "maintenance")
+            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 2 * * ?"))
+            .build();
     }
 }
 ```
 
-### MapReduce 任务（分片 + 汇总）
-
-> 源码：`ruoyi-job/.../snailjob/TestMapReduceAnnotation1.java`
-
-在 Map 基础上增加 Reduce 汇总。
+### 方案三：分布式任务调度平台（XXL-Job 等）
 
 ```java
-import com.aizuda.snailjob.client.job.core.annotation.ReduceExecutor;
-import com.aizuda.snailjob.client.job.core.dto.ReduceArgs;
-
+// 通用模式：注解标记任务处理器
 @Component
-@JobExecutor(name = "testMapReduceAnnotation1")
-public class TestMapReduceAnnotation1 {
-
-    @MapExecutor
-    public ExecuteResult rootMapExecute(MapArgs mapArgs, MapHandler mapHandler) {
-        // 拆分数据（同 Map 任务）
-        return mapHandler.doMap(partition, "doCalc");
-    }
+public class OrderCleanupJobHandler {
 
-    @MapExecutor(taskName = "doCalc")
-    public ExecuteResult doCalc(MapArgs mapArgs) {
-        List<Integer> sourceList = (List<Integer>) mapArgs.getMapResult();
-        return ExecuteResult.success(sourceList.stream().mapToInt(i -> i).sum());
-    }
+    @Autowired
+    private OrderService orderService;
 
-    @ReduceExecutor
-    public ExecuteResult reduceExecute(ReduceArgs reduceArgs) {
-        List<?> mapResults = reduceArgs.getMapResult();
-        int total = mapResults.stream()
-            .mapToInt(i -> Integer.parseInt((String) i)).sum();
-        SnailJobLog.REMOTE.info("Reduce 汇总，最终总和: {}", total);
-        return ExecuteResult.success(total);
+    // 具体注解取决于所选平台
+    // 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;  // 抛出异常触发平台重试
+        }
     }
 }
 ```
 
----
-
-## 执行模式对比
+### 执行模式
 
 | 模式 | 特点 | 适用场景 |
 |------|------|---------|
-| **集群** | 多节点竞争，只有一个执行 | 订单处理、数据汇总 |
-| **广播** | 所有节点都执行 | 清理缓存、刷新配置 |
-| **静态分片** | 按固定规则分片 | 已知数据范围的批处理 |
-| **Map** | 动态分片 | 运行时确定分片 |
-| **MapReduce** | 动态分片 + 结果汇总 | 分布式计算（求和、统计） |
-
----
-
-## 日志工具
-
-```java
-import com.aizuda.snailjob.common.log.SnailJobLog;
-
-SnailJobLog.LOCAL.info("本地日志: {}", msg);   // 输出到控制台/日志文件
-SnailJobLog.REMOTE.info("远程日志: {}", msg);  // 上报到 SnailJob 控制台
-```
+| **集群/随机** | 多节点竞争，只有一个执行 | 订单处理、数据汇总 |
+| **广播** | 所有节点都执行 | 清理本地缓存、刷新配置 |
+| **分片** | 按规则分片，每节点处理部分数据 | 大数据量批处理 |
+| **MapReduce** | 动态分片 + 结果汇总 | 分布式计算、统计 |
 
 ---
 
@@ -228,87 +180,98 @@ SnailJobLog.REMOTE.info("远程日志: {}", msg);  // 上报到 SnailJob 控制
 
 ```java
 @Component
-@JobExecutor(name = "orderCleanupJob")
-public class OrderCleanupJob {
+public class [你的任务类] {
+
+    private static final Logger log = LoggerFactory.getLogger([你的任务类].class);
 
     @Autowired
-    private IOrderService orderService;
+    private [你的业务Service] bizService;
+
+    public void execute(String params) {
+        long startTime = System.currentTimeMillis();
+        log.info("[任务开始] 参数: {}", params);
 
-    public ExecuteResult jobExecute(JobArgs jobArgs) {
-        SnailJobLog.REMOTE.info("开始清理过期订单");
         try {
-            String params = jobArgs.getJobParams();
-            int days = StringUtils.isBlank(params) ? 30 : Integer.parseInt(params);
-            int count = orderService.cleanupExpiredOrders(days);
-            SnailJobLog.REMOTE.info("清理完成，删除 {} 条", count);
-            return ExecuteResult.success("清理 " + count + " 条");
+            // 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) {
-            SnailJobLog.REMOTE.error("清理失败: {}", e.getMessage());
+            log.error("[任务失败] {}", e.getMessage(), e);
             throw e;  // 抛出异常触发重试
         }
     }
 }
 ```
 
-### 幂等性保证
-
-```java
-public ExecuteResult jobExecute(JobArgs jobArgs) {
-    String orderId = jobArgs.getJobParams();
-    if (paymentService.isSynced(orderId)) {
-        return ExecuteResult.success("已同步，跳过");
-    }
-    paymentService.sync(orderId);
-    return ExecuteResult.success("同步成功");
-}
-```
+### 重试策略对比
 
-### 错误处理
+| 策略 | 说明 | 适用场景 |
+|------|------|---------|
+| 固定间隔 | 每次间隔相同（如 30s） | 网络抖动、临时故障 |
+| 指数退避 | 间隔逐倍增加（1s, 2s, 4s, 8s...） | 服务恢复中 |
+| Cron 重试 | 按 Cron 表达式重试 | 定点重试 |
+| 最大次数 | 限制最大重试次数 | 防止无限重试 |
 
-```java
-// 抛出异常 -> SnailJob 自动重试
-throw e;
+### Cron 表达式速查
 
-// 返回 failure -> 不会触发重试（慎用）
-return ExecuteResult.failure("失败");
-```
+| 表达式 | 含义 |
+|--------|------|
+| `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 * ?` | 每月最后一天零点 |
 
 ---
 
-## 控制台配置
-
-1. **任务管理** -> **新增任务**
-2. 任务名称与 `@JobExecutor(name)` 一致
-3. 任务类型：集群/广播/静态分片/Map/MapReduce
-4. 触发类型：CRON / 固定频率
-
-### 重试策略
-
-| 策略 | 说明 | 场景 |
-|------|------|------|
-| 固定间隔 | 每次间隔相同 | 网络抖动 |
-| 指数退避 | 间隔逐倍增加 | 服务恢复中 |
-| CRON | 按表达式重试 | 定点重试 |
+## 常见错误
 
----
-
-## 常见问题
+```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);
+    }
+}
 
-| 问题 | 排查步骤 |
-|------|---------|
-| 任务不执行 | 1.检查 `snail-job.enabled: true` 2.`@JobExecutor(name)` 与控制台一致 3.SnailJob 服务是否启动 |
-| @Scheduled vs SnailJob | 简单/<100个任务 -> @Scheduled；需重试/监控/分布式 -> SnailJob |
-| 查看任务日志 | 本地 -> 应用日志；远程 -> SnailJob 控制台 -> 任务实例 -> 查看日志 |
+// 2. @Scheduled 默认单线程，长任务阻塞其他任务
+// 应配置线程池（见上文 SchedulingConfig）
 
----
+// 3. 多实例部署未做互斥
+// @Scheduled 每个实例都执行 -> 数据重复处理
+// 应使用分布式锁（Redis / 数据库）或分布式调度平台
 
-## 核心文件位置
+// 4. 任务非幂等
+public void syncData() {
+    insertAll(fetchData());  // 重复执行会插入重复数据
+}
+// 应先检查是否已处理
 
-| 文件 | 路径 |
-|------|------|
-| 注解方式 | `ruoyi-modules/ruoyi-job/.../snailjob/TestAnnoJobExecutor.java` |
-| 类方式 | `ruoyi-modules/ruoyi-job/.../snailjob/TestClassJobExecutor.java` |
-| 广播任务 | `ruoyi-modules/ruoyi-job/.../snailjob/TestBroadcastJob.java` |
-| 静态分片 | `ruoyi-modules/ruoyi-job/.../snailjob/TestStaticShardingJob.java` |
-| Map 任务 | `ruoyi-modules/ruoyi-job/.../snailjob/TestMapJobAnnotation.java` |
-| MapReduce | `ruoyi-modules/ruoyi-job/.../snailjob/TestMapReduceAnnotation1.java` |
+// 5. 任务内开启大事务
+@Transactional
+public void processAllOrders() {
+    // 处理百万条数据在一个事务中 -> 内存溢出、锁超时
+}
+// 应分批处理，每批独立事务
+```