|
|
@@ -0,0 +1,363 @@
|
|
|
+ # 定时规则使用示例
|
|
|
+
|
|
|
+ ## 概述
|
|
|
+
|
|
|
+ 定时规则支持两种模式:
|
|
|
+ 1. **CRON模式**:重复周期调度(适用于固定周期的常规灌溉计划)
|
|
|
+ 2. **SIMPLE模式**:间隔周期调度(适用于临时性或有限次数的灌溉计划)
|
|
|
+
|
|
|
+ ## 一、CRON模式
|
|
|
+
|
|
|
+ ### 1.1 CRON模式参数说明
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 说明 | 示例 |
|
|
|
+| -------------- | -------- | ---- | ---------------------- | --------------------- |
|
|
|
+| taskId | Long | 是 | 关联的任务ID | 123 |
|
|
|
+| ruleName | String | 否 | 规则名称(用于标识) | "每周一三五凌晨2点" |
|
|
|
+| scheduleType | String | 是 | 定时类型,固定为"CRON" | "CRON" |
|
|
|
+| executeTime | String | 是 | 执行时间(HH:mm:ss) | "02:00:00" |
|
|
|
+| repeatWeekdays | String | 是 | 重复周期-星期几 | "1,3,5" |
|
|
|
+| validStartDate | DateTime | 否 | 有效开始时间 | "2026-03-01 00:00:00" |
|
|
|
+| validEndDate | DateTime | 否 | 有效结束时间 | "2026-12-31 23:59:59" |
|
|
|
+| enabled | Boolean | 否 | 是否启用(默认true) | true |
|
|
|
+
|
|
|
+ **星期对照表:**
|
|
|
+ - 1 = 周一(Monday)
|
|
|
+ - 2 = 周二(Tuesday)
|
|
|
+ - 3 = 周三(Wednesday)
|
|
|
+ - 4 = 周四(Thursday)
|
|
|
+ - 5 = 周五(Friday)
|
|
|
+ - 6 = 周六(Saturday)
|
|
|
+ - 7 = 周日(Sunday)
|
|
|
+
|
|
|
+ ### 1.2 CRON模式使用示例
|
|
|
+
|
|
|
+ #### 示例1:每周一、三、五凌晨2点执行
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每周一三五凌晨2点",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "02:00:00",
|
|
|
+ "repeatWeekdays": "1,3,5",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 后端会自动生成 CRON 表达式:`0 0 2 ? * MON,WED,FRI`
|
|
|
+
|
|
|
+ #### 示例2:每周二、四下午5点执行(带有效期)
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每周二四下午5点(春季灌溉)",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "17:00:00",
|
|
|
+ "repeatWeekdays": "2,4",
|
|
|
+ "validStartDate": "2026-03-01 00:00:00",
|
|
|
+ "validEndDate": "2026-05-31 23:59:59",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 后端会自动生成 CRON 表达式:`0 0 17 ? * TUE,THU`
|
|
|
+
|
|
|
+ 有效期说明:
|
|
|
+ - 在 2026-03-01 之前不会触发
|
|
|
+ - 在 2026-05-31 之后不再触发
|
|
|
+ - 只在有效期内的每周二、四下午5点触发
|
|
|
+
|
|
|
+ #### 示例3:每天凌晨3点执行
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每天凌晨3点",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "03:00:00",
|
|
|
+ "repeatWeekdays": "1,2,3,4,5,6,7",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 后端会自动生成 CRON 表达式:`0 0 3 ? * MON,TUE,WED,THU,FRI,SAT,SUN`
|
|
|
+
|
|
|
+ #### 示例4:仅周末执行(周六、周日上午8点)
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "周末灌溉",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "08:00:00",
|
|
|
+ "repeatWeekdays": "6,7",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 后端会自动生成 CRON 表达式:`0 0 8 ? * SAT,SUN`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+ ## 二、SIMPLE模式
|
|
|
+
|
|
|
+ ### 2.1 SIMPLE模式参数说明
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 说明 | 示例 |
|
|
|
+| ------------ | -------- | ---- | ------------------------- | --------------------- |
|
|
|
+| taskId | Long | 是 | 关联的任务ID | 123 |
|
|
|
+| ruleName | String | 否 | 规则名称(用于标识) | "连续10天灌溉计划" |
|
|
|
+| scheduleType | String | 是 | 定时类型,固定为"SIMPLE" | "SIMPLE" |
|
|
|
+| startTime | DateTime | 是 | 起始时间(包含日期+时间) | "2026-03-10 06:00:00" |
|
|
|
+| intervalDays | Integer | 是 | 执行间隔天数 | 1 |
|
|
|
+| totalTimes | Integer | 是 | 执行总次数 | 10 |
|
|
|
+| enabled | Boolean | 否 | 是否启用(默认true) | true |
|
|
|
+
|
|
|
+ ### 2.2 SIMPLE模式使用示例
|
|
|
+
|
|
|
+ #### 示例1:连续10天,每天早上6点执行
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "连续10天灌溉计划",
|
|
|
+ "scheduleType": "SIMPLE",
|
|
|
+ "startTime": "2026-03-10 06:00:00",
|
|
|
+ "intervalDays": 1,
|
|
|
+ "totalTimes": 10,
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 执行计划:
|
|
|
+ - 第1次:2026-03-10 06:00:00
|
|
|
+ - 第2次:2026-03-11 06:00:00
|
|
|
+ - 第3次:2026-03-12 06:00:00
|
|
|
+ - ...
|
|
|
+ - 第10次:2026-03-19 06:00:00(执行完毕后自动停用)
|
|
|
+
|
|
|
+ #### 示例2:每隔3天执行一次,共执行5次
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "隔天灌溉计划",
|
|
|
+ "scheduleType": "SIMPLE",
|
|
|
+ "startTime": "2026-03-15 07:30:00",
|
|
|
+ "intervalDays": 3,
|
|
|
+ "totalTimes": 5,
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 执行计划:
|
|
|
+ - 第1次:2026-03-15 07:30:00
|
|
|
+ - 第2次:2026-03-18 07:30:00
|
|
|
+ - 第3次:2026-03-21 07:30:00
|
|
|
+ - 第4次:2026-03-24 07:30:00
|
|
|
+ - 第5次:2026-03-27 07:30:00(执行完毕后自动停用)
|
|
|
+
|
|
|
+ #### 示例3:每周执行一次,共执行4次
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "月度维护计划",
|
|
|
+ "scheduleType": "SIMPLE",
|
|
|
+ "startTime": "2026-04-01 10:00:00",
|
|
|
+ "intervalDays": 7,
|
|
|
+ "totalTimes": 4,
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ 执行计划:
|
|
|
+ - 第1次:2026-04-01 10:00:00
|
|
|
+ - 第2次:2026-04-08 10:00:00
|
|
|
+ - 第3次:2026-04-15 10:00:00
|
|
|
+ - 第4次:2026-04-22 10:00:00(执行完毕后自动停用)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+ ## 三、API接口使用示例
|
|
|
+
|
|
|
+ ### 3.1 创建定时规则
|
|
|
+
|
|
|
+ **请求:**
|
|
|
+ ```http
|
|
|
+ POST /v2/{tenantId}/irrigation-task-schedule
|
|
|
+ Content-Type: application/json
|
|
|
+
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每周一三五凌晨2点",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "02:00:00",
|
|
|
+ "repeatWeekdays": "1,3,5",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ **响应:**
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "id": 456,
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每周一三五凌晨2点",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "cronExpression": "0 0 2 ? * MON,WED,FRI",
|
|
|
+ "executeTime": "02:00:00",
|
|
|
+ "repeatWeekdays": "1,3,5",
|
|
|
+ "enabled": true,
|
|
|
+ "status": 1,
|
|
|
+ "quartzJobName": "TASK_123_RULE_456",
|
|
|
+ "quartzTriggerName": "TRIGGER_123_RULE_456"
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ ### 3.2 查询任务的所有定时规则
|
|
|
+
|
|
|
+ **请求:**
|
|
|
+ ```http
|
|
|
+ GET /v2/{tenantId}/irrigation-task-schedule/task/123
|
|
|
+ ```
|
|
|
+
|
|
|
+ **响应:**
|
|
|
+ ```json
|
|
|
+ [
|
|
|
+ {
|
|
|
+ "id": 456,
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每周一三五凌晨2点",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "cronExpression": "0 0 2 ? * MON,WED,FRI",
|
|
|
+ "executeTime": "02:00:00",
|
|
|
+ "repeatWeekdays": "1,3,5",
|
|
|
+ "enabled": true,
|
|
|
+ "status": 1
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": 457,
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "连续10天灌溉计划",
|
|
|
+ "scheduleType": "SIMPLE",
|
|
|
+ "startTime": "2026-03-10 06:00:00",
|
|
|
+ "intervalDays": 1,
|
|
|
+ "totalTimes": 10,
|
|
|
+ "executedCount": 3,
|
|
|
+ "enabled": true,
|
|
|
+ "status": 1
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ ```
|
|
|
+
|
|
|
+ ### 3.3 更新定时规则
|
|
|
+
|
|
|
+ **请求:**
|
|
|
+ ```http
|
|
|
+ PUT /v2/{tenantId}/irrigation-task-schedule/456
|
|
|
+ Content-Type: application/json
|
|
|
+
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "每周一三五凌晨3点(已调整)",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "03:00:00",
|
|
|
+ "repeatWeekdays": "1,3,5",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ ### 3.4 启用/禁用定时规则
|
|
|
+
|
|
|
+ **启用:**
|
|
|
+ ```http
|
|
|
+ POST /v2/{tenantId}/irrigation-task-schedule/456/enable
|
|
|
+ ```
|
|
|
+
|
|
|
+ **禁用:**
|
|
|
+ ```http
|
|
|
+ POST /v2/{tenantId}/irrigation-task-schedule/456/disable
|
|
|
+ ```
|
|
|
+
|
|
|
+ ### 3.5 删除定时规则
|
|
|
+
|
|
|
+ **删除单个:**
|
|
|
+ ```http
|
|
|
+ DELETE /v2/{tenantId}/irrigation-task-schedule/456
|
|
|
+ ```
|
|
|
+
|
|
|
+ **批量删除:**
|
|
|
+ ```http
|
|
|
+ DELETE /v2/{tenantId}/irrigation-task-schedule/batch
|
|
|
+ Content-Type: application/json
|
|
|
+
|
|
|
+ [456, 457, 458]
|
|
|
+ ```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+ ## 四、多规则配置示例
|
|
|
+
|
|
|
+ 一个任务可以同时配置多个定时规则,CRON模式和SIMPLE模式可以共存。
|
|
|
+
|
|
|
+ ### 示例:组合配置
|
|
|
+
|
|
|
+ 为同一个任务(taskId=123)配置以下规则:
|
|
|
+
|
|
|
+ #### 规则1:工作日早上灌溉
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "工作日早上灌溉",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "06:00:00",
|
|
|
+ "repeatWeekdays": "1,2,3,4,5",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ #### 规则2:周末中午灌溉
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "周末中午灌溉",
|
|
|
+ "scheduleType": "CRON",
|
|
|
+ "executeTime": "12:00:00",
|
|
|
+ "repeatWeekdays": "6,7",
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ #### 规则3:临时加强灌溉(连续7天)
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "taskId": 123,
|
|
|
+ "ruleName": "临时加强灌溉",
|
|
|
+ "scheduleType": "SIMPLE",
|
|
|
+ "startTime": "2026-03-15 18:00:00",
|
|
|
+ "intervalDays": 1,
|
|
|
+ "totalTimes": 7,
|
|
|
+ "enabled": true
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+ ## 五、注意事项
|
|
|
+
|
|
|
+ ### 5.1 CRON模式注意事项
|
|
|
+
|
|
|
+ 1. **自动生成CRON表达式**:后端会根据 `executeTime` 和 `repeatWeekdays` 自动生成标准的 CRON 表达式,前端无需手动构造
|
|
|
+ 2. **有效期控制**:可通过 `validStartDate` 和 `validEndDate` 控制规则的生效时间范围
|
|
|
+ 3. **星期格式**:`repeatWeekdays` 使用数字表示,多个星期用逗号分隔
|
|
|
+ 4. **时间格式**:`executeTime` 必须为 HH:mm:ss 格式
|
|
|
+
|
|
|
+ ### 5.2 SIMPLE模式注意事项
|
|
|
+
|
|
|
+ 1. **自动停用**:当已执行次数达到 `totalTimes` 后,规则会自动标记为已完成状态
|
|
|
+ 2. **执行计数**:系统会自动记录 `executedCount`,无需手动维护
|
|
|
+ 3. **间隔计算**:`intervalDays` 表示两次执行之间的天数间隔
|
|
|
+ 4. **首次执行**:`startTime` 即为第一次执行的时间
|