Jayhaw/wf-platform-equipment-automationV2 @ 94b71f65a57759fd071263f5b4542b59bc3c8aa1

# 定时规则使用示例

## 概述

定时规则支持两种模式：

CRON模式：重复周期调度（适用于固定周期的常规灌溉计划）
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点执行

 {
   "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点执行（带有效期）

 {
   "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点执行

 {
   "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点）

 {
   "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点执行

 {
   "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次

 {
   "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次

 {
   "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 创建定时规则

请求：

 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
 }

响应：

 {
   "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 查询任务的所有定时规则

请求：

 GET /v2/{tenantId}/irrigation-task-schedule/task/123

响应：

 [
   {
     "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 更新定时规则

请求：

 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 启用/禁用定时规则

启用：

 POST /v2/{tenantId}/irrigation-task-schedule/456/enable

禁用：

 POST /v2/{tenantId}/irrigation-task-schedule/456/disable

### 3.5 删除定时规则

删除单个：

 DELETE /v2/{tenantId}/irrigation-task-schedule/456

批量删除：

 DELETE /v2/{tenantId}/irrigation-task-schedule/batch
 Content-Type: application/json

 [456, 457, 458]

## 四、多规则配置示例

一个任务可以同时配置多个定时规则，CRON模式和SIMPLE模式可以共存。

### 示例：组合配置

为同一个任务（taskId=123）配置以下规则：

#### 规则1：工作日早上灌溉

 {
   "taskId": 123,
   "ruleName": "工作日早上灌溉",
   "scheduleType": "CRON",
   "executeTime": "06:00:00",
   "repeatWeekdays": "1,2,3,4,5",
   "enabled": true
 }

#### 规则2：周末中午灌溉

 {
   "taskId": 123,
   "ruleName": "周末中午灌溉",
   "scheduleType": "CRON",
   "executeTime": "12:00:00",
   "repeatWeekdays": "6,7",
   "enabled": true
 }

#### 规则3：临时加强灌溉（连续7天）

 {
   "taskId": 123,
   "ruleName": "临时加强灌溉",
   "scheduleType": "SIMPLE",
   "startTime": "2026-03-15 18:00:00",
   "intervalDays": 1,
   "totalTimes": 7,
   "enabled": true
 }

## 五、注意事项

### 5.1 CRON模式注意事项

自动生成CRON表达式：后端会根据 executeTime 和 repeatWeekdays 自动生成标准的 CRON 表达式，前端无需手动构造
有效期控制：可通过 validStartDate 和 validEndDate 控制规则的生效时间范围
星期格式：repeatWeekdays 使用数字表示，多个星期用逗号分隔
时间格式：executeTime 必须为 HH:mm:ss 格式

### 5.2 SIMPLE模式注意事项

自动停用：当已执行次数达到 totalTimes 后，规则会自动标记为已完成状态
执行计数：系统会自动记录 executedCount，无需手动维护
间隔计算：intervalDays 表示两次执行之间的天数间隔
首次执行：startTime 即为第一次执行的时间

定时规则使用示例.md 9.1 KB Cronologia Originale

定时规则使用示例.md 9.1 KB

Cronologia Originale