# 定时规则使用示例

 ## 概述

 定时规则支持两种模式：
  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` 即为第一次执行的时间