zcloud_gbs_safetyDutyList/docs/安全责任清单接口文档.md

# 安全责任清单 - 前端联调接口文档

> 基础路径：`/{gateway}` （gateway 配置值为 `safetyDutyList`，即实际前缀为 `/safetyDutyList`）
>
> 通用响应结构（COLA框架）：
> - `PageResponse<T>`：分页响应，包含 `data`(列表)、`totalCount`(总数)、`pageSize`、`pageIndex`
> - `SingleResponse<T>`：单对象响应，包含 `data`
> - `MultiResponse<T>`：列表响应，包含 `data`
> - `Response`：无数据响应，仅包含 `success`、`errCode`、`errMessage`

---

## 一、安全责任清单（TaskListController）

### 1.1 获取任务清单列表

- **URL**：`POST /safetyDutyList/taskList/list`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| createCorpId | Long | 否 | 创建公司ID |
| executeCorpId | Long | 否 | 执行公司ID |
| executeUserId | Long | 否 | 执行人员ID |
| taskListName | String | 否 | 清单名称（模糊查询） |
| taskLevel | Integer | 否 | 任务级别：1-企业级 2-部门级 3-班组级 |
| feedbackStatus | Integer | 否 | 反馈状态：1-正常 2-异常 |
| switchFlag | Integer | 否 | 开启/关闭：0-关 1-开 |
| menuPath | String | 否 | 菜单路径 |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "taskListName": "安全",
  "taskLevel": 1
}
```

**响应数据**：`PageResponse<TaskListCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| taskListId | String | 清单UUID（业务主键） |
| taskListName | String | 清单名称 |
| taskLevel | Integer | 任务级别：1-企业级 2-部门级 3-班组级 |
| responsibilityPost | String | 责任岗位 |
| switchFlag | Integer | 开启/关闭：0-关 1-开 |
| status | Integer | 状态：1-进行中 2-已完成 3-已关闭 |
| periodStartTime | String | 执行周期开始时间（yyyy-MM-dd HH:mm:ss） |
| periodEndTime | String | 执行周期结束时间（yyyy-MM-dd HH:mm:ss） |
| ratingScore | BigDecimal | 清单分数 |
| ratingUserId | Long | 评分人ID |
| ratingUserName | String | 评分人姓名 |
| ratingDepartmentId | Long | 评分部门ID |
| ratingDepartmentName | String | 评分部门名称 |
| issueStatus | Integer | 下发状态：0-未下发 1-已下发 |
| issueTime | String | 下发时间（yyyy-MM-dd HH:mm:ss） |
| executeCorpId | Long | 执行公司ID |
| executeCorpName | String | 执行公司名称 |
| executeDepartmentId | Long | 执行部门ID |
| executeDepartmentName | String | 执行部门名称 |
| executeUserId | Long | 执行人员ID |
| executeUserName | String | 执行人员名称 |
| taskCount | Integer | 任务数 |
| feedbackStatus | Integer | 反馈状态：1-正常 2-异常 |

---

### 1.2 新增任务清单

- **URL**：`POST /safetyDutyList/taskList/save`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListName | String | **是** | 清单名称 |
| taskLevel | Integer | **是** | 任务级别：1-企业级 2-部门级 3-班组级 |
| responsibilityPost | String | **是** | 责任岗位 |
| switchFlag | Integer | **是** | 是否启用：1-启用 0-不启用 |

**请求示例**：
```json
{
  "taskListName": "2025年安全责任清单",
  "taskLevel": 1,
  "responsibilityPost": "安全管理岗",
  "switchFlag": 1
}
```

**响应数据**：`SingleResponse<TaskListCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| taskListId | String | 清单UUID（业务主键） |
| taskListName | String | 清单名称 |
| taskLevel | Integer | 任务级别：1-企业级 2-部门级 3-班组级 |
| responsibilityPost | String | 责任岗位 |
| switchFlag | Integer | 开启/关闭：0-关 1-开 |
| status | Integer | 状态：1-进行中 2-已完成 3-已关闭 |
| periodStartTime | String | 执行周期开始时间 |
| periodEndTime | String | 执行周期结束时间 |
| ratingScore | BigDecimal | 清单分数 |
| ratingUserId | Long | 评分人ID |
| ratingUserName | String | 评分人姓名 |
| ratingDepartmentId | Long | 评分部门ID |
| ratingDepartmentName | String | 评分部门名称 |
| issueStatus | Integer | 下发状态：0-未下发 1-已下发 |
| issueTime | String | 下发时间 |
| executeCorpId | Long | 执行公司ID |
| executeCorpName | String | 执行公司名称 |
| executeDepartmentId | Long | 执行部门ID |
| executeDepartmentName | String | 执行部门名称 |
| executeUserId | Long | 执行人员ID |
| executeUserName | String | 执行人员名称 |
| taskCount | Integer | 任务数 |
| feedbackStatus | Integer | 反馈状态：1-正常 2-异常 |

---

### 1.3 修改任务清单

- **URL**：`POST /safetyDutyList/taskList/edit`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListId | String | **是** | 清单UUID（业务主键） |
| taskListName | String | **是** | 清单名称 |
| taskLevel | Integer | **是** | 任务级别：1-企业级 2-部门级 3-班组级 |
| responsibilityPost | String | **是** | 责任岗位 |
| switchFlag | Integer | **是** | 是否启用：1-启用 0-不启用 |

**请求示例**：
```json
{
  "taskListId": "uuid-xxx",
  "taskListName": "2025年安全责任清单（修改）",
  "taskLevel": 1,
  "responsibilityPost": "安全管理岗",
  "switchFlag": 1
}
```

**响应数据**：`SingleResponse`

---

### 1.4 删除任务清单

- **URL**：`POST /safetyDutyList/taskList/delete/{id}`

**路径参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | **是** | 清单主键ID |

**请求示例**：
```
POST /safetyDutyList/taskList/delete/1
```

**响应数据**：`Response`

---

### 1.5 开启/关闭任务清单

- **URL**：`POST /safetyDutyList/taskList/switchFlag`
- **Content-Type**：`application/json`

> 注意：调用此接口即表示要关闭任务清单

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListId | String | **是** | 清单UUID |
| switchFlag | Integer | **是** | 开启/关闭：0-关 1-开 |

**请求示例**：
```json
{
  "taskListId": "uuid-xxx",
  "switchFlag": 0
}
```

**响应数据**：`SingleResponse`

---

### 1.6 关闭清单

- **URL**：`POST /safetyDutyList/taskList/close`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListId | String | **是** | 清单UUID |

**请求示例**：
```json
{
  "taskListId": "uuid-xxx"
}
```

**响应数据**：`SingleResponse`

---

### 1.7 任务下发

- **URL**：`POST /safetyDutyList/taskList/issue`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListId | String | **是** | 清单UUID |
| executeCorpId | Long | **是** | 执行公司ID |
| executeDepartmentId | Long | **是** | 执行部门ID |
| executeUserId | Long | **是** | 执行人员ID |
| periodStartTime | String | **是** | 执行周期开始时间（yyyy-MM-dd HH:mm:ss） |
| periodEndTime | String | **是** | 执行周期结束时间（yyyy-MM-dd HH:mm:ss） |

**请求示例**：
```json
{
  "taskListId": "uuid-xxx",
  "executeCorpId": 100,
  "executeDepartmentId": 200,
  "executeUserId": 300,
  "periodStartTime": "2025-01-01 00:00:00",
  "periodEndTime": "2025-12-31 23:59:59"
}
```

**响应数据**：`SingleResponse`

---

## 二、任务详情（TaskDetailController）

### 2.1 获取任务列表

- **URL**：`POST /safetyDutyList/taskDetail/list`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| taskListId | String | 否 | 清单表主键ID |
| taskContent | String | 否 | 执行内容 |
| taskPeriodStart | String | 否 | 任务周期开始时间 |
| taskPeriodEnd | String | 否 | 任务周期结束时间 |
| feedbackCycleType | Integer | 否 | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| feedbackStatus | Integer | 否 | 反馈状态：1-正常 2-异常 |
| taskStatus | Integer | 否 | 任务状态：1-进行中 2-已完成 3-已关闭 |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "taskListId": "uuid-xxx",
  "taskStatus": 1
}
```

**响应数据**：`PageResponse<TaskDetailFullCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键ID |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 任务清单UUID |
| executeContent | String | 执行内容 |
| feedbackCycleType | Integer | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| taskScore | BigDecimal | 任务分值 |
| taskRating | BigDecimal | 当前得分（任务评分） |
| taskStatus | Integer | 任务状态：1-进行中 2-已完成 3-已关闭 |
| feedbackCount | Integer | 反馈次数 |
| feedbackStatus | Integer | 反馈状态：1-正常 2-异常 |
| currentPeriodFeedback | Boolean | 当前节点是否反馈 |
| exceptionList | Array | 异常列表（见FeedbackExceptionCO） |

**exceptionList 子对象（FeedbackExceptionCO）**：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| feedbackExceptionId | String | 反馈异常UUID |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 任务清单UUID |
| exceptionPeriodFlag | String | 异常周期标识 |
| exceptionPeriodStartTime | String | 异常周期开始时间 |
| exceptionPeriodEndTime | String | 异常周期结束时间 |
| exceptionType | Integer | 异常类型：1-未按时反馈 2-反馈内容异常 3-其他 |
| exceptionContent | String | 反馈异常信息 |
| exceptionTime | String | 异常时间 |
| createTime | String | 创建时间 |
| taskListName | String | 清单名称 |
| executeContent | String | 执行内容 |

---

### 2.2 新增任务

- **URL**：`POST /safetyDutyList/taskDetail/save`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListId | String | **是** | 清单表主键ID |
| executeContent | String | 否 | 执行内容 |
| feedbackCycleType | Integer | **是** | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| taskScore | BigDecimal | 否 | 任务分值 |

**请求示例**：
```json
{
  "taskListId": "uuid-xxx",
  "executeContent": "每月检查消防设施",
  "feedbackCycleType": 1,
  "taskScore": 10.0
}
```

**响应数据**：`SingleResponse<TaskDetailCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| taskDetailId | String | 明细UUID（业务主键） |
| taskListId | String | 任务清单ID |
| executeContent | String | 执行内容 |
| feedbackCycleType | Integer | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| feedbackCycleName | String | 反馈周期名称 |
| taskStatus | Integer | 任务状态：1-进行中 2-已完成 3-已关闭 |
| feedbackStatus | Integer | 反馈状态：1-正常 2-存在异常 |
| taskScore | BigDecimal | 任务分值 |
| taskRating | BigDecimal | 任务评分 |
| ratingTime | String | 评分时间（yyyy-MM-dd HH:mm:ss） |
| ratingDepartmentId | Long | 评分部门ID |
| ratingUserId | Long | 评分人ID |

---

### 2.3 批量保存任务

- **URL**：`POST /safetyDutyList/taskDetail/saveBatch`
- **Content-Type**：`application/json`

> 保存逻辑：以传参列表为准，id为空时新增，id非空时更新，数据库中有但传参中没有的则删除。
> 校验规则：保存后该清单下所有任务分值之和不能超过100

**请求参数**：`List<TaskDetailSaveBatchCmd>`（JSON数组）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 否 | 主键ID（为空时新增，非空时更新） |
| taskListId | String | **是** | 清单表主键ID |
| executeContent | String | 否 | 执行内容 |
| feedbackCycleType | Integer | **是** | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| taskScore | BigDecimal | 否 | 任务分值 |

**请求示例**：
```json
[
  {
    "id": null,
    "taskListId": "uuid-xxx",
    "executeContent": "新增任务内容",
    "feedbackCycleType": 1,
    "taskScore": 20.0
  },
  {
    "id": 5,
    "taskListId": "uuid-xxx",
    "executeContent": "更新任务内容",
    "feedbackCycleType": 2,
    "taskScore": 30.0
  }
]
```

**响应数据**：`MultiResponse<TaskDetailCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| taskDetailId | String | 明细UUID（业务主键） |
| taskListId | String | 任务清单ID |
| executeContent | String | 执行内容 |
| feedbackCycleType | Integer | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| feedbackCycleName | String | 反馈周期名称 |
| taskStatus | Integer | 任务状态：1-进行中 2-已完成 3-已关闭 |
| feedbackStatus | Integer | 反馈状态：1-正常 2-存在异常 |
| taskScore | BigDecimal | 任务分值 |
| taskRating | BigDecimal | 任务评分 |
| ratingTime | String | 评分时间（yyyy-MM-dd HH:mm:ss） |
| ratingDepartmentId | Long | 评分部门ID |
| ratingUserId | Long | 评分人ID |

---

### 2.4 编辑任务

- **URL**：`POST /safetyDutyList/taskDetail/edit`
- **Content-Type**：`application/json`

> 校验规则：编辑后该清单下所有任务分值之和不能超过100

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskDetailId | String | **是** | 任务详情UUID |
| taskListId | String | **是** | 清单表主键ID |
| executeContent | String | 否 | 执行内容 |
| feedbackCycleType | Integer | **是** | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| taskScore | BigDecimal | 否 | 任务分值 |

**请求示例**：
```json
{
  "taskDetailId": "uuid-detail-xxx",
  "taskListId": "uuid-xxx",
  "executeContent": "每月检查消防设施（修改）",
  "feedbackCycleType": 1,
  "taskScore": 15.0
}
```

**响应数据**：`SingleResponse<TaskDetailCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| taskDetailId | String | 明细UUID（业务主键） |
| taskListId | String | 任务清单ID |
| executeContent | String | 执行内容 |
| feedbackCycleType | Integer | 反馈周期类型：1-每月 2-季度 3-半年 4-年 |
| feedbackCycleName | String | 反馈周期名称 |
| taskStatus | Integer | 任务状态：1-进行中 2-已完成 3-已关闭 |
| feedbackStatus | Integer | 反馈状态：1-正常 2-存在异常 |
| taskScore | BigDecimal | 任务分值 |
| taskRating | BigDecimal | 任务评分 |
| ratingTime | String | 评分时间（yyyy-MM-dd HH:mm:ss） |
| ratingDepartmentId | Long | 评分部门ID |
| ratingUserId | Long | 评分人ID |

---

### 2.5 获取任务详情

- **URL**：`GET /safetyDutyList/taskDetail/{detailId}`

**路径参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| detailId | String | **是** | 任务详情UUID |

**请求示例**：
```
GET /safetyDutyList/taskDetail/uuid-detail-xxx
```

**响应数据**：`SingleResponse<TaskDetailInfoCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键ID |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 清单表主键ID |
| taskListName | String | 清单名称 |
| taskLevel | Integer | 任务级别 |
| responsibilityPost | String | 责任岗位 |
| feedbackCycleType | Integer | 反馈周期类型 |
| taskScore | BigDecimal | 任务分值 |
| executeContent | String | 执行内容 |

---

### 2.6 关闭任务

- **URL**：`POST /safetyDutyList/taskDetail/close`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskDetailId | String | **是** | 任务UUID |

**请求示例**：
```json
{
  "taskDetailId": "uuid-detail-xxx"
}
```

**响应数据**：`Response`

---

### 2.7 更新任务评分

- **URL**：`POST /safetyDutyList/taskDetail/updateScore`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskDetailId | String | **是** | 任务UUID |
| taskRating | BigDecimal | **是** | 分数（不能超过任务分值） |
| ratingDeptId | Long | **是** | 评分部门ID |
| ratingUserId | Long | **是** | 评分人员ID |

**请求示例**：
```json
{
  "taskDetailId": "uuid-detail-xxx",
  "taskRating": 8.5,
  "ratingDeptId": 200,
  "ratingUserId": 300
}
```

**响应数据**：`Response`

---

## 三、执行反馈（FeedbackController）

### 3.1 提交反馈

- **URL**：`POST /safetyDutyList/feedback/save`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskListId | String | **是** | 任务清单ID |
| taskDetailId | String | **是** | 清单明细ID |
| feedbackContent | String | **是** | 反馈内容 |
| feedbackCorpId | Long | 否 | 反馈人公司ID |
| feedbackDepartmentId | Long | 否 | 反馈人部门ID |
| feedbackUserId | Long | 否 | 反馈人ID |

**请求示例**：
```json
{
  "taskListId": "uuid-xxx",
  "taskDetailId": "uuid-detail-xxx",
  "feedbackContent": "本月已按计划完成消防设施检查",
  "feedbackUserId": 300
}
```

**响应数据**：`SingleResponse<FeedbackCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| feedbackId | String | 反馈UUID（业务主键） |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 任务清单UUID |
| feedbackTime | String | 反馈时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodFlag | String | 反馈周期标识 |
| feedbackPeriodStartTime | String | 反馈周期开始时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodEndTime | String | 反馈周期结束时间（yyyy-MM-dd HH:mm:ss） |
| feedbackContent | String | 反馈内容 |
| feedbackUserId | Long | 反馈人ID |
| feedbackUserName | String | 反馈人姓名 |
| feedbackCorpId | Long | 反馈人公司ID |
| feedbackCorpName | String | 反馈人公司名称 |
| feedbackDepartmentId | Long | 反馈人部门ID |
| feedbackDepartmentName | String | 反馈人部门名称 |
| executeContent | String | 执行内容 |
| taskListName | String | 清单名称 |
| createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |

---

### 3.2 删除反馈

- **URL**：`POST /safetyDutyList/feedback/delete/{id}`

**路径参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | **是** | 反馈记录主键ID |

**请求示例**：
```
POST /safetyDutyList/feedback/delete/1
```

**响应数据**：`Response`

---

### 3.3 编辑反馈

- **URL**：`POST /safetyDutyList/feedback/edit`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| feedbackId | String | **是** | 反馈UUID |
| feedbackContent | String | **是** | 反馈内容 |

**请求示例**：
```json
{
  "feedbackId": "uuid-feedback-xxx",
  "feedbackContent": "修改后的反馈内容"
}
```

**响应数据**：`SingleResponse<FeedbackCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| feedbackId | String | 反馈UUID（业务主键） |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 任务清单UUID |
| feedbackTime | String | 反馈时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodFlag | String | 反馈周期标识 |
| feedbackPeriodStartTime | String | 反馈周期开始时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodEndTime | String | 反馈周期结束时间（yyyy-MM-dd HH:mm:ss） |
| feedbackContent | String | 反馈内容 |
| feedbackUserId | Long | 反馈人ID |
| feedbackUserName | String | 反馈人姓名 |
| feedbackCorpId | Long | 反馈人公司ID |
| feedbackCorpName | String | 反馈人公司名称 |
| feedbackDepartmentId | Long | 反馈人部门ID |
| feedbackDepartmentName | String | 反馈人部门名称 |
| executeContent | String | 执行内容 |
| taskListName | String | 清单名称 |
| createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |

---

### 3.4 获取反馈周期分组列表

- **URL**：`POST /safetyDutyList/feedback/periodGroupList`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskDetailId | String | **是** | 任务ID |
| feedbackTimeStart | String | 否 | 反馈时间开始（格式：yyyy-MM-dd） |
| feedbackTimeEnd | String | 否 | 反馈时间结束（格式：yyyy-MM-dd） |

**请求示例**：
```json
{
  "taskDetailId": "uuid-detail-xxx",
  "feedbackTimeStart": "2025-01-01",
  "feedbackTimeEnd": "2025-06-30"
}
```

**响应数据**：`MultiResponse<FeedbackPeriodGroupCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| taskDetailId | String | 任务ID |
| feedbackPeriodStartTime | String | 反馈周期开始时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodEndTime | String | 反馈周期结束时间（yyyy-MM-dd HH:mm:ss） |
| feedbackCount | Integer | 反馈次数 |
| feedbackUserName | String | 反馈人姓名 |
| feedbackPeriodFlag | String | 周期标识 |

---

### 3.5 获取反馈列表

- **URL**：`POST /safetyDutyList/feedback/list`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| taskDetailId | String | 否 | 任务详情ID |
| taskListId | String | 否 | 任务清单ID |
| feedbackPeriodFlag | String | 否 | 周期标识 |
| feedbackCorpId | Long | 否 | 反馈人公司ID |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "taskDetailId": "uuid-detail-xxx",
  "feedbackPeriodFlag": "2025-Q1"
}
```

**响应数据**：`PageResponse<FeedbackCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| feedbackId | String | 反馈UUID |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 任务清单UUID |
| feedbackTime | String | 反馈时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodStartTime | String | 反馈周期开始时间 |
| feedbackPeriodEndTime | String | 反馈周期结束时间 |
| feedbackPeriodFlag | String | 反馈周期标识 |
| feedbackContent | String | 反馈内容 |
| feedbackUserId | Long | 反馈人ID |
| feedbackUserName | String | 反馈人姓名 |
| feedbackCorpId | Long | 反馈人公司ID |
| feedbackCorpName | String | 反馈人公司名称 |
| feedbackDepartmentId | Long | 反馈人部门ID |
| feedbackDepartmentName | String | 反馈人部门名称 |
| executeContent | String | 执行内容 |
| taskListName | String | 清单名称 |
| createTime | String | 创建时间 |

---

### 3.6 获取反馈详情

- **URL**：`GET /safetyDutyList/feedback/{feedbackId}`

**路径参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| feedbackId | String | **是** | 反馈UUID |

**请求示例**：
```
GET /safetyDutyList/feedback/uuid-feedback-xxx
```

**响应数据**：`SingleResponse<FeedbackInfoCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键ID |
| feedbackId | String | 反馈UUID |
| taskDetailId | String | 任务详情ID |
| executeContent | String | 执行内容 |
| feedbackCycleType | Integer | 反馈周期类型 |
| feedbackContent | String | 反馈内容 |
| feedbackTime | String | 反馈时间（yyyy-MM-dd HH:mm:ss） |
| feedbackPeriodStartTime | String | 反馈周期开始时间 |
| feedbackPeriodEndTime | String | 反馈周期结束时间 |

---

### 3.7 获取异常记录列表

- **URL**：`POST /safetyDutyList/feedback/exception/list`
- **Content-Type**：`application/json`

> 注意：此接口暂未开放

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| taskListId | String | 否 | 任务清单ID |
| exceptionType | Integer | 否 | 异常类型：1-未按时反馈 2-反馈内容异常 3-其他 |
| exceptionPeriodFlag | String | 否 | 异常周期标识 |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "taskListId": "uuid-xxx",
  "exceptionType": 1
}
```

**响应数据**：`PageResponse<FeedbackExceptionCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 主键 |
| feedbackExceptionId | String | 反馈异常UUID |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 任务清单UUID |
| exceptionPeriodFlag | String | 异常周期标识 |
| exceptionPeriodStartTime | String | 异常周期开始时间 |
| exceptionPeriodEndTime | String | 异常周期结束时间 |
| exceptionType | Integer | 异常类型：1-未按时反馈 2-反馈内容异常 3-其他 |
| exceptionContent | String | 反馈异常信息 |
| exceptionTime | String | 异常时间 |
| createTime | String | 创建时间 |
| taskListName | String | 清单名称 |
| executeContent | String | 执行内容 |

---

## 四、统计分析（StatisticsController）

### 4.1 获取企业统计（股份端）

- **URL**：`POST /safetyDutyList/statistics/corpStatistics`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| corpName | String | 否 | 企业名称（模糊查询） |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "corpName": "XX公司"
}
```

**响应数据**：`PageResponse<CorpStatisticsCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| corpId | Long | 公司ID |
| corpName | String | 公司名称 |
| completedTaskCount | Integer | 已完成任务数 |
| closedTaskCount | Integer | 已关闭任务数 |
| totalTaskCount | Integer | 年度执行任务总数 |

---

### 4.2 获取企业评价列表

- **URL**：`POST /safetyDutyList/statistics/evaluationList`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| corpName | String | 否 | 企业名称（模糊查询） |
| scoreStatus | Integer | 否 | 评分状态：0-未评分 1-已评分 |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "corpName": "XX公司",
  "scoreStatus": 0
}
```

**响应数据**：`PageResponse<EvaluationListCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| corpId | Long | 公司ID |
| corpName | String | 公司名称 |
| listCount | Integer | 清单数量 |

---

### 4.3 获取企业任务下发统计数

- **URL**：`POST /safetyDutyList/statistics/issueStatistics`
- **Content-Type**：`application/json`

**请求参数**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页条数（默认10） |
| corpName | String | 否 | 企业名称（模糊查询） |

**请求示例**：
```json
{
  "pageIndex": 1,
  "pageSize": 10,
  "corpName": "XX公司"
}
```

**响应数据**：`PageResponse<IssueStatisticsCO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| corpId | Long | 公司ID |
| corpName | String | 公司名称 |
| issueCount | Integer | 任务清单下发数 |

---

## 附录：枚举值速查

| 枚举 | 值 | 说明 |
|------|------|------|
| 任务级别(taskLevel) | 1 | 企业级 |
| | 2 | 部门级 |
| | 3 | 班组级 |
| 开关标识(switchFlag) | 0 | 关闭 |
| | 1 | 开启 |
| 清单状态(status) | 1 | 进行中 |
| | 2 | 已完成 |
| | 3 | 已关闭 |
| 下发状态(issueStatus) | 0 | 未下发 |
| | 1 | 已下发 |
| 反馈周期类型(feedbackCycleType) | 1 | 每月 |
| | 2 | 每季度 |
| | 3 | 每半年 |
| | 4 | 每年 |
| 反馈状态(feedbackStatus) | 1 | 正常 |
| | 2 | 异常 |
| 异常类型(exceptionType) | 1 | 未按时反馈 |
| | 2 | 反馈内容异常 |
| | 3 | 其他 |
| 评分状态(scoreStatus) | 0 | 未评分 |
| | 1 | 已评分 |

**周期标识格式说明**：

| 反馈周期类型 | 格式 | 示例 |
|------|------|------|
| 1-每月 | yyyy-MM | 2026-05 |
| 2-每季度 | yyyy-Qn | 2026-Q1 |
| 3-每半年 | yyyy-Hn | 2026-H1 |
| 4-每年 | yyyy-Y | 2026-Y |

**反馈异常检测定时任务说明**：

定时任务于每月1日00:00:00执行，检测逻辑如下：

1. 查询所有已下发且周期时间完整的清单（issue_status=1，period_start_time和period_end_time不为空，且period_end_time不超过当前时间1个月）
2. 遍历每个清单下的所有任务，以清单的周期起始时间判断是否仍处于首个反馈周期内
3. 若仍处于首周期（首周期尚未结束），跳过检测，不判定异常
4. 若已过首周期，检查上一阶段是否有反馈记录，无反馈则判定为异常

**首周期判断规则**：将清单的periodStartTime和当前时间分别生成周期标识，若相同则仍在首周期内。

| 清单起始时间 | 当前时间 | 周期类型 | 首周期标识 | 当前周期标识 | 是否跳过 |
|------|------|------|------|------|------|
| 2026-07-01 | 2026-07-12 | 1-每月 | 2026-07 | 2026-07 | 跳过 |
| 2026-07-01 | 2026-08-01 | 1-每月 | 2026-07 | 2026-08 | 检查2026-07 |
| 2026-07-01 | 2026-07-12 | 2-每季度 | 2026-Q3 | 2026-Q3 | 跳过 |
| 2026-07-01 | 2026-10-01 | 2-每季度 | 2026-Q3 | 2026-Q4 | 检查2026-Q3 |
| 2026-07-01 | 2026-07-12 | 3-每半年 | 2026-H2 | 2026-H2 | 跳过 |
| 2026-07-01 | 2027-01-01 | 3-每半年 | 2026-H2 | 2027-H1 | 检查2026-H2 |
| 2026-07-01 | 2026-07-12 | 4-每年 | 2026-Y | 2026-Y | 跳过 |
| 2026-07-01 | 2027-01-01 | 4-每年 | 2026-Y | 2027-Y | 检查2026-Y |