# 设备保养任务接口文档

## 概述

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

---

## 接口列表

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

**请求地址**: `GET /deviceMaintenanceTask/listPage`

**请求参数**:

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

**响应示例**:

```json
{
  "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 | 否 | 备注 |

**响应示例**:

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

---

### 3. 更新保养任务

**请求地址**: `POST /deviceMaintenanceTask/update`

**请求头**: `Content-Type: application/json`

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

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

**响应示例**:

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

---

### 4. 启用/禁用保养任务

**请求地址**: `POST /deviceMaintenanceTask/changeEnable`

**请求头**: `Content-Type: application/json`

**请求参数**:

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

**响应示例**:

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

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

---

### 5. 删除保养任务

**请求地址**: `DELETE /deviceMaintenanceTask/delete`

**请求头**: `Content-Type: application/json`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| - | Long[] | 是 | 任务ID数组（请求体直接传数组） |

**请求示例**:

```json
[1, 2, 3]
```

**响应示例**:

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

---

## 前端使用示例

### 新增每周保养任务

```javascript
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)
});
```

### 启用/禁用任务

```javascript
// 启用任务
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 | 更新时间 |

---

## 注意事项

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