设备保养任务接口文档

概述

设备保养任务模块用于管理设备的定时保养计划，支持多种频率类型（每日、每周、每月、每季度、每年），并可启用或禁用任务。

接口列表

1. 分页查询保养任务列表

请求地址: GET /deviceMaintenanceTask/listPage

请求参数:

参数名	类型	必填	说明
current	Long	否	当前页码，默认1
size	Long	否	每页条数，默认10
taskName	String	否	任务名称（模糊查询）
areaId	Long	否	设备区域ID
isEnabled	Integer	否	是否启用（1=启用，0=禁用）

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "taskName": "设备A,设备B",
        "taskId": 100,
        "areaId": 10,
        "areaName": "生产车间",
        "deviceModel": "型号A,型号B",
        "deviceLedgerIdsStr": "100,101",
        "frequencyType": "WEEKLY",
        "frequencyDetail": "MON,14:30",
        "nextExecutionTime": "2026-06-08T14:30:00",
        "lastExecutionTime": "2026-06-01T14:30:00",
        "isEnabled": 1,
        "remarks": "备注信息",
        "registrantId": 1,
        "registrant": "张三",
        "registrationDate": "2026-06-01",
        "createTime": "2026-06-01T10:00:00",
        "updateTime": "2026-06-01T10:00:00"
      }
    ],
    "total": 100,
    "current": 1,
    "size": 10
  }
}

2. 新增保养任务

请求地址: POST /deviceMaintenanceTask/add

请求头: Content-Type: application/json

请求参数:

参数名	类型	必填	说明
taskName	String	否	任务名称（如不传则根据设备名称自动生成）
taskId	Long	否	设备ID（单个设备时使用）
deviceLedgerIds	Long[]	否	设备ID数组（多个设备时使用）
deviceLedgerIdsStr	String	否	设备ID字符串，逗号分隔
areaId	Long	否	设备区域ID
frequencyType	String	是	频次类型，见下方说明
frequencyDetail	String	是	频次详情，格式见下方说明
isEnabled	Integer	否	是否启用（1=启用，0=禁用），默认1
remarks	String	否	备注

响应示例:

{
  "code": 200,
  "msg": "添加成功"
}

3. 更新保养任务

请求地址: POST /deviceMaintenanceTask/update

请求头: Content-Type: application/json

请求参数: 同新增接口，需额外传入 id 字段

参数名	类型	必填	说明
id	Long	是	任务ID
...	...	...	其他字段同新增接口

响应示例:

{
  "code": 200,
  "msg": "更新成功"
}

4. 启用/禁用保养任务

请求地址: POST /deviceMaintenanceTask/changeEnable

请求头: Content-Type: application/json

请求参数:

参数名	类型	必填	说明
id	Long	是	任务ID
isEnabled	Integer	是	是否启用（1=启用，0=禁用）

响应示例:

{
  "code": 200,
  "msg": "更新成功"
}

业务逻辑说明:
- 启用任务时会自动恢复定时调度
- 禁用任务时会暂停定时调度
- 如果任务没有下次执行时间，会自动计算

5. 删除保养任务

请求地址: DELETE /deviceMaintenanceTask/delete

请求头: Content-Type: application/json

请求参数:

参数名	类型	必填	说明

| - | Long[] | 是 | 任务ID数组（请求体直接传数组） |

请求示例:

[1, 2, 3]

响应示例:

{
  "code": 200,
  "msg": "删除成功"
}

频率类型说明

frequencyType 可选值

值	说明	frequencyDetail 格式
DAILY	每日	`HH:mm`
WEEKLY	每周	`星期,HH:mm`
MONTHLY	每月	`日,HH:mm`
QUARTERLY	每季度	`起始月份,日,HH:mm`
YEARLY	每年	`月份,日,HH:mm`

frequencyDetail 格式详解

1. 每日（DAILY）

格式：HH:mm

示例：
- 14:30 - 每天 14:30 执行

2. 每周（WEEKLY）

格式：星期,HH:mm

星期可选值：MON, TUE, WED, THU, FRI, SAT, SUN

示例：
- MON,14:30 - 每周一 14:30 执行
- FRI,09:00 - 每周五 09:00 执行

3. 每月（MONTHLY）

格式：日,HH:mm

示例：
- 15,14:30 - 每月15日 14:30 执行
- 01,09:00 - 每月1日 09:00 执行
- 31,18:00 - 每月最后一天（如月份不足31天则取最后一天）

4. 每季度（QUARTERLY）

格式：起始月份,日,HH:mm

说明：从指定月份开始，每隔3个月执行一次

示例：
- 1,15,14:30 - 1月、4月、7月、10月的15日 14:30 执行
- 3,10,09:00 - 3月、6月、9月、12月的10日 09:00 执行

5. 每年（YEARLY）

格式：月份,日,HH:mm

示例：
- 6,15,14:30 - 每年6月15日 14:30 执行
- 12,31,23:59 - 每年12月31日 23:59 执行

前端使用示例

新增每周保养任务

const task = {
  deviceLedgerIds: [100, 101],  // 设备ID数组
  areaId: 10,                   // 区域ID
  frequencyType: 'WEEKLY',      // 每周
  frequencyDetail: 'MON,14:30', // 每周一14:30
  isEnabled: 1,                 // 启用
  remarks: '每周例行保养'
};

fetch('/deviceMaintenanceTask/add', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(task)
});

启用/禁用任务

// 启用任务
fetch('/deviceMaintenanceTask/changeEnable', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 1, isEnabled: 1 })
});

// 禁用任务
fetch('/deviceMaintenanceTask/changeEnable', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 1, isEnabled: 0 })
});

数据字典

isEnabled 字段

值	说明
0	禁用
1	启用

返回字段说明

字段名	类型	说明
id	Long	任务ID
taskName	String	任务名称（多个设备用逗号分隔）
taskId	Long	主设备ID
areaId	Long	设备区域ID
areaName	String	设备区域名称
deviceModel	String	设备型号（多个用逗号分隔）
deviceLedgerIdsStr	String	设备ID字符串（逗号分隔）
frequencyType	String	频次类型
frequencyDetail	String	频次详情
nextExecutionTime	DateTime	下次执行时间
lastExecutionTime	DateTime	最后执行时间
isEnabled	Integer	是否启用
remarks	String	备注
registrantId	Long	录入人ID
registrant	String	录入人姓名
registrationDate	Date	录入日期
createTime	DateTime	创建时间
updateTime	DateTime	更新时间

注意事项

设备选择：可以传入 deviceLedgerIds 数组或 deviceLedgerIdsStr 字符串指定多个设备
任务名称：如不传 taskName，系统会根据设备名称自动生成
下次执行时间：新增或更新时会自动计算下次执行时间
启用/禁用：禁用任务不会删除定时器，只是暂停执行；启用后会恢复
删除任务：删除任务会同时移除相关的定时调度