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

# 安全责任清单接口文档

## 一、概述

### 1.1 项目结构

项目采用六边形架构（Hexagonal Architecture），遵循 CQRS 模式：

```
zcloud_gbs_safety_accountability_list/
├── start/                    # 应用启动入口
├── web-adapter/             # 控制器层（REST API）
├── web-app/                 # 应用服务层（Command/Query 执行器）
├── web-domain/              # 领域模型层
├── web-infrastructure/      # 基础设施层（持久化实现）
└── web-client/              # 客户端层（DTO、CO、Cmd、Qry）
```

### 1.2 模块职责

| 模块 | 职责 |
|-----|------|
| web-adapter | Controller 层，负责接收 HTTP 请求，调用 Service |
| web-app | 应用层，包含 Command（写操作）和 Query（读操作）执行器 |
| web-domain | 领域层，包含领域模型、枚举、Gateway 接口 |
| web-infrastructure | 基础设施层，包含 DO、Repository、Mapper 实现 |
| web-client | 客户端层，包含 DTO（Cmd、Qry）和 CO（Client Object） |

### 1.3 命名规范

| 类型 | 命名规范 | 示例 |
|-----|---------|------|
| Controller | `{Entity}Controller` | `TaskListController` |
| Service 接口 | `{Entity}ServiceI` | `TaskListServiceI` |
| Command | `{Entity}AddCmd`、`{Entity}UpdateCmd` | `TaskListAddCmd` |
| Query | `{Entity}PageQry`、`{Entity}Qry` | `TaskListPageQry` |
| Client Object | `{Entity}CO` | `TaskListCO` |
| Data Object | `{Entity}DO` | `TaskListDO` |
| Gateway | `{Entity}Gateway` | `TaskListGateway` |
| Repository | `{Entity}Repository` | `TaskListRepository` |
| Mapper | `{Entity}Mapper` | `TaskListMapper` |
| AddExe | `{Entity}AddExe` | `TaskListAddExe` |
| QueryExe | `{Entity}QueryExe` | `TaskListQueryExe` |
| Convertor | `{Entity}CoConvertor` | `TaskListCoConvertor` |

### 1.4 响应结构规范

项目使用 COLA 框架的响应类，位于 `com.alibaba.cola.dto` 包下：

| 响应类 | 说明 | 使用场景 |
|-------|------|---------|
| `SingleResponse<T>` | 单条数据响应 | 新增、修改、详情查询等返回单个对象 |
| `PageResponse<T>` | 分页数据响应 | 列表分页查询 |
| `MultiResponse<T>` | 多条数据响应 | 不分页的列表查询 |
| `Response` | 无数据响应 | 删除、关闭等无返回数据的操作 |

**响应结构示例**：

```java
// SingleResponse<T> - 单条数据响应
{
    "code": "200",
    "message": "success",
    "data": { ... }
}

// PageResponse<T> - 分页数据响应
{
    "code": "200",
    "message": "success",
    "data": [ ... ],
    "totalCount": 100,
    "pageSize": 10,
    "pageIndex": 1
}

// MultiResponse<T> - 多条数据响应
{
    "code": "200",
    "message": "success",
    "data": [ ... ]
}

// Response - 无数据响应
{
    "code": "200",
    "message": "success"
}
```

**Controller 使用示例**：

```java
// 新增 - 返回单条数据
@PostMapping("/save")
public SingleResponse<TaskListCO> add(@RequestBody TaskListAddCmd cmd) {
    return taskListService.add(cmd);
}

// 分页查询 - 返回分页数据
@PostMapping("/list")
public PageResponse<TaskListCO> list(@RequestBody TaskListPageQry qry) {
    return taskListService.listPage(qry);
}

// 列表查询（不分页） - 返回多条数据
@PostMapping("/listAll")
public MultiResponse<TaskListCO> listAll(@RequestBody TaskListQry qry) {
    return MultiResponse.of(taskListService.listAll(qry));
}

// 删除 - 无数据返回
@PostMapping("/{id}")
public Response remove(@PathVariable("id") Long id) {
    taskListService.remove(id);
    return SingleResponse.buildSuccess();
}
```

### 1.5 表清单

| 序号 | 表名 | 表中文名 |
|-----|------|---------|
| 1 | safety_accountability_task_list | 任务清单表 |
| 2 | safety_accountability_task_detail | 任务清单详细表 |
| 3 | safety_accountability_feedback | 执行反馈表 |
| 4 | safety_accountability_feedback_exception | 反馈异常信息表 |

```
建表语句：
-- =============================================
-- 任务清单表
-- =============================================
CREATE TABLE `safety_accountability_task_list` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
    `task_list_id` varchar(64) NOT NULL COMMENT '清单UUID（业务主键）',
    `task_list_name` varchar(255) NOT NULL COMMENT '清单名称',
    `task_level` tinyint(2) NOT NULL COMMENT '任务级别：1-企业级 2-部门级 3-班组级',
    `responsibility_post` varchar(255) DEFAULT NULL COMMENT '责任岗位',
    `switch_flag` tinyint(1) NOT NULL DEFAULT '1' COMMENT '开启/关闭：0-关 1-开',
    `status` tinyint(2) NOT NULL DEFAULT '1' COMMENT '状态：1-进行中 2-已完成 3-已关闭',
    `period_start_time` datetime NOT NULL COMMENT '执行周期开始时间',
    `period_end_time` datetime NOT NULL COMMENT '执行周期结束时间',
    `score` decimal(5,2) DEFAULT NULL COMMENT '评分数',
    `score_user_id` bigint(20) DEFAULT NULL COMMENT '评分人ID',
    `score_department_id` bigint(20) DEFAULT NULL COMMENT '评分部门ID',
    `create_corp_id` bigint(20) DEFAULT NULL COMMENT '创建公司ID',
    `create_department_id` bigint(20) DEFAULT NULL COMMENT '创建部门ID',
    `create_user_id` bigint(20) DEFAULT NULL COMMENT '创建人ID',
    `issue_status` tinyint(4) DEFAULT '0' COMMENT '下发状态：0-未下发 1-已下发',
    `issue_time` datetime DEFAULT NULL COMMENT '下发时间',
    `execute_corp_id` bigint(20) DEFAULT NULL COMMENT '执行公司ID',
    `execute_department_id` bigint(20) DEFAULT NULL COMMENT '执行部门ID',
    `execute_user_id` bigint(20) DEFAULT NULL COMMENT '执行人员ID',
    `close_time` datetime DEFAULT NULL COMMENT '关闭时间',
    `delete_enum` varchar(32) DEFAULT 'FALSE' COMMENT '删除标识：TRUE/FALSE',
    `remarks` varchar(500) DEFAULT NULL COMMENT '备注',
    `create_name` varchar(50) DEFAULT NULL COMMENT '创建人姓名',
    `update_name` varchar(50) DEFAULT NULL COMMENT '更新人姓名',
    `tenant_id` bigint(20) DEFAULT NULL COMMENT '租户ID',
    `org_id` bigint(20) DEFAULT NULL COMMENT '单位ID',
    `version` int(11) DEFAULT '0' COMMENT '版本',
    `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
    `create_id` bigint(20) DEFAULT NULL COMMENT '创建人ID',
    `update_id` bigint(20) DEFAULT NULL COMMENT '修改人ID',
    `env` varchar(50) DEFAULT NULL COMMENT '环境标识',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_task_list_id` (`task_list_id`),
    KEY `idx_create_corp_id` (`create_corp_id`),
    KEY `idx_execute_corp_id` (`execute_corp_id`),
    KEY `idx_execute_user_id` (`execute_user_id`),
    KEY `idx_status` (`status`),
    KEY `idx_period_time` (`period_start_time`, `period_end_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='任务清单表';

-- =============================================
-- 任务清单详细表
-- =============================================
CREATE TABLE `safety_accountability_task_detail` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
    `task_detail_id` varchar(64) NOT NULL COMMENT '任务详情UUID（业务主键）',
    `task_list_id` varchar(64) NOT NULL COMMENT '任务清单主键（关联任务清单表）',
    `execute_content` text COMMENT '执行内容',
    `feedback_cycle` tinyint(4) NOT NULL COMMENT '反馈周期：1-每月 2-季度 3-半年 4-年',
    `task_status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '任务状态：1-进行中 2-已完成 3-已关闭',
    `feedback_status` tinyint(4) DEFAULT '1' COMMENT '反馈状态：1-正常 2-存在异常',
    `task_score` decimal(5,2) DEFAULT NULL COMMENT '任务分值',
    `task_rating` decimal(5,2) DEFAULT NULL COMMENT '任务评分',
    `score_time` datetime DEFAULT NULL COMMENT '评分时间',
    `score_department_id` bigint(20) DEFAULT NULL COMMENT '评分部门ID',
    `score_user_id` bigint(20) DEFAULT NULL COMMENT '评分人ID',
    `delete_enum` varchar(32) DEFAULT 'FALSE' COMMENT '删除标识：TRUE/FALSE',
    `remarks` varchar(500) DEFAULT NULL COMMENT '备注',
    `create_name` varchar(50) DEFAULT NULL COMMENT '创建人姓名',
    `update_name` varchar(50) DEFAULT NULL COMMENT '更新人姓名',
    `tenant_id` bigint(20) DEFAULT NULL COMMENT '租户ID',
    `org_id` bigint(20) DEFAULT NULL COMMENT '单位ID',
    `version` int(11) DEFAULT '0' COMMENT '版本',
    `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
    `create_id` bigint(20) DEFAULT NULL COMMENT '创建人ID',
    `update_id` bigint(20) DEFAULT NULL COMMENT '修改人ID',
    `env` varchar(50) DEFAULT NULL COMMENT '环境标识',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_task_detail_id` (`task_detail_id`),
    KEY `idx_task_list_id` (`task_list_id`),
    KEY `idx_task_status` (`task_status`),
    KEY `idx_feedback_status` (`feedback_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='任务清单详细表';

-- =============================================
-- 执行反馈表
-- =============================================
CREATE TABLE `safety_accountability_feedback` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
    `feedback_id` varchar(64) NOT NULL COMMENT '反馈UUID（业务主键）',
    `task_detail_id` varchar(64) NOT NULL COMMENT '任务详情UUID（关联任务清单详细表）',
    `task_list_id` varchar(64) NOT NULL COMMENT '任务清单UUID（冗余字段，便于查询）',
    `feedback_time` datetime NOT NULL COMMENT '反馈时间',
    `feedback_period_start_time` datetime NOT NULL COMMENT '反馈周期开始时间（用于回显）',
    `feedback_period_end_time` datetime NOT NULL COMMENT '反馈周期结束时间（用于回显）',
    `feedback_period_flag` varchar(20) NOT NULL COMMENT '反馈周期标识（格式：2026-05表示月，2026-Q1表示季度，2026-H1表示半年，2026表示年）',
    `feedback_content` text COMMENT '反馈内容',
    `feedback_user_id` bigint(20) DEFAULT NULL COMMENT '反馈人ID',
    `feedback_corp_id` bigint(20) DEFAULT NULL COMMENT '反馈人公司ID',
    `feedback_department_id` bigint(20) DEFAULT NULL COMMENT '反馈人部门ID',
    `delete_enum` varchar(32) DEFAULT 'FALSE' COMMENT '删除标识：TRUE/FALSE',
    `remarks` varchar(500) DEFAULT NULL COMMENT '备注',
    `create_name` varchar(50) DEFAULT NULL COMMENT '创建人姓名',
    `update_name` varchar(50) DEFAULT NULL COMMENT '更新人姓名',
    `tenant_id` bigint(20) DEFAULT NULL COMMENT '租户ID',
    `org_id` bigint(20) DEFAULT NULL COMMENT '单位ID',
    `version` int(11) DEFAULT '0' COMMENT '版本',
    `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
    `create_id` bigint(20) DEFAULT NULL COMMENT '创建人ID',
    `update_id` bigint(20) DEFAULT NULL COMMENT '修改人ID',
    `env` varchar(50) DEFAULT NULL COMMENT '环境标识',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_feedback_id` (`feedback_id`),
    KEY `idx_task_detail_id` (`task_detail_id`),
    KEY `idx_task_list_id` (`task_list_id`),
    KEY `idx_feedback_time` (`feedback_time`),
    KEY `idx_feedback_period_flag` (`feedback_period_flag`),
    KEY `idx_feedback_user_id` (`feedback_user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='执行反馈表';

-- =============================================
-- 反馈异常信息表
-- =============================================
CREATE TABLE `safety_accountability_feedback_exception` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
    `feedback_exception_id` varchar(64) NOT NULL COMMENT '反馈异常UUID（业务主键）',
    `task_detail_id` varchar(64) NOT NULL COMMENT '任务详情主键（关联任务清单详细表）',
    `task_list_id` varchar(64) DEFAULT NULL COMMENT '任务清单主键（冗余字段）',
    `exception_period_flag` varchar(20) DEFAULT NULL COMMENT '异常周期标识',
    `feedback_exception_period_time` varchar(255) DEFAULT NULL COMMENT '反馈周期（用于回显）',
    `exception_type` tinyint(4) DEFAULT 1 COMMENT '异常类型：1-未按时反馈 2-反馈内容异常 3-其他',
    `exception_content` text COMMENT '反馈异常信息',
    `exception_time` datetime DEFAULT NULL COMMENT '异常时间',
    `delete_enum` varchar(32) DEFAULT 'FALSE' COMMENT '删除标识：TRUE/FALSE',
    `remarks` varchar(500) DEFAULT NULL COMMENT '备注',
    `create_name` varchar(50) DEFAULT NULL COMMENT '创建人姓名',
    `update_name` varchar(50) DEFAULT NULL COMMENT '更新人姓名',
    `tenant_id` bigint(20) DEFAULT NULL COMMENT '租户ID',
    `org_id` bigint(20) DEFAULT NULL COMMENT '单位ID',
    `version` int(11) DEFAULT '0' COMMENT '版本',
    `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
    `create_id` bigint(20) DEFAULT NULL COMMENT '创建人ID',
    `update_id` bigint(20) DEFAULT NULL COMMENT '修改人ID',
    `env` varchar(50) DEFAULT NULL COMMENT '环境标识',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_feedback_exception_id` (`feedback_exception_id`),
    KEY `idx_task_detail_id` (`task_detail_id`),
    KEY `idx_task_list_id` (`task_list_id`),
    KEY `idx_exception_period` (`exception_period`),
    KEY `idx_exception_type` (`exception_type`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='反馈异常信息表';
```
---

## 二、枚举值说明

### 2.1 任务级别 (taskLevel)

| 值 | 说明 |
|---|------|
| 1 | 企业级 |
| 2 | 部门级 |
| 3 | 班组级 |

### 2.2 任务状态 (status)

| 值 | 说明 |
|---|------|
| 1 | 进行中 |
| 2 | 已完成 |
| 3 | 已关闭 |

### 2.3 反馈周期 (feedbackCycle)

| 值 | 说明 | 周期标识格式  |
|---|------|---------|
| 1 | 每月 | 2026-05 |
| 2 | 每季度 | 2026-Q1 |
| 3 | 半年 | 2026-H1 |
| 4 | 年 | 2026-Y  |

### 2.4 反馈状态 (feedbackStatus)

| 值 | 说明 |
|---|----|
| 1 | 正常 |
| 2 | 异常 |

### 2.5 开关状态 (switchFlag)

| 值 | 说明 |
|---|------|
| 0 | 关闭 |
| 1 | 开启 |

### 2.6 异常类型 (exceptionType)

| 值 | 说明 |
|---|------|
| 1 | 未按时反馈 |
| 2 | 反馈内容异常 |
| 3 | 其他 |

### 2.7 评分状态 (scoreStatus)

| 值 | 说明 |
|---|------|
| 0 | 未评分 |
| 1 | 已评分 |

---

## 三、任务清单接口

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

**接口路径**：`POST /{gateway}/safetyAccountability/taskList/list`

**接口描述**：分页查询任务清单列表

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| pageIndex | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |
| corpId | Long | 否 | 公司ID |
| taskListName | String | 否 | 清单名称（模糊查询） |
| taskLevel | Integer | 否 | 任务级别：1-企业级 2-部门级 3-班组级 |
| feedbackStatus | Integer | 否 | 反馈状态：1-正常 2-存在异常 |
| switchFlag | Integer | 否 | 开关状态：0-关 1-开 |

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

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| id | Long | 主键ID |
| taskListId | String | 清单UUID（业务主键） |
| taskListName | String | 清单名称 |
| taskLevel | Integer | 任务级别：1-企业级 2-部门级 3-班组级 |
| responsibilityPost | String | 责任岗位 |
| switchFlag | Integer | 开关状态：0-关 1-开 |
| status | Integer | 状态：1-进行中 2-已完成 3-已关闭 |
| executeDepartmentId | Long | 执行部门ID |
| executeDepartmentName | String | 执行部门名称 |
| executeUserId | Long | 执行人员ID |
| executeUserName | String | 执行人员名称 |
| taskCount | Integer | 任务数 |
| periodStartTime | String | 执行周期开始时间 |
| periodEndTime | String | 执行周期结束时间 |
| taskStatus | Integer | 任务状态 1-进行中 2-已完成 3-已关闭|
| feedbackStatus | Integer | 反馈状态：1-正常 2-异常 |
| scoreDepartmentId | Long | 评分部门ID |
| scoreDepartmentName | String | 评分部门名称 |
| scoreUserId | Long | 评分人员ID |
| scoreUserName | String | 评分人员名称 |
| score | BigDecimal | 清单分数 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
            "id": 1,
            "taskListId": "abc123def456",
            "taskListName": "2026年度安全生产责任清单",
            "taskLevel": 1,
            "responsibilityPost": "安全员",
            "switchFlag": 1,
            "status": 1,
            "executeDepartmentId": 200001,
            "executeDepartmentName": "安全管理部",
            "executeUserId": 300001,
            "executeUserName": "张三",
            "taskCount": 5,
            "periodStartTime": "2026-01-01 00:00:00",
            "periodEndTime": "2026-12-31 23:59:59",
            "taskStatus": 1,
            "feedbackStatus": 1,
            "scoreDepartmentId": 200001,
            "scoreDepartmentName": "安全管理部",
            "scoreUserId": 400001,
            "scoreUserName": "李四",
            "score": 85.50
        }
    ],
    "totalCount": 100,
    "pageSize": 10,
    "pageIndex": 1
}
```

---

### 3.2 新增任务清单

**接口路径**：`POST /{gateway}/safetyAccountability/taskList/save`

**接口描述**：新增任务清单

**请求参数**：

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

**请求示例**：
```json
{
    "taskListName": "2026年度安全生产责任清单",
    "taskLevel": 1,
    "responsibilityPost": "安全员",
    "switchFlag": 1
}
```

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| id | Long | 主键ID |
| taskListId | String | 清单UUID（业务主键） |
| taskListName | String | 清单名称 |
| taskLevel | Integer | 任务级别 |
| taskLevelName | String | 任务级别名称 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": {
        "id": 1,
        "taskListId": "abc123def456",
        "taskListName": "2026年度安全生产责任清单",
        "taskLevel": 1,
        "taskLevelName": "企业级"
    }
}
```

---

### 3.3 关闭清单

**接口路径**：`POST /{gateway}/safetyAccountability/taskList/close`

**接口描述**：手动关闭任务清单

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskListId | String | 是 | 清单UUID |

**请求示例**：
```json
{
    "taskListId": "abc123def456"
}
```

**响应参数**：无

**响应示例**：
```json
{
    "code": "200",
    "message": "success"
}
```

---

### 3.4 任务下发

**接口路径**：`POST /{gateway}/safetyAccountability/taskList/issue`

**接口描述**：将任务清单下发给执行人（仅可下发开启状态的清单）

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskListId | String | 是 | 清单UUID（仅开启状态的清单） |
| executeCorpId | Long | 是 | 执行公司ID |
| executeUserId | Long | 是 | 执行人员ID |
| periodStartTime | String | 是 | 执行周期开始日期（格式：yyyy-MM-dd HH:mm:ss） |
| periodEndTime | String | 是 | 执行周期结束日期（格式：yyyy-MM-dd HH:mm:ss） |

**请求示例**：
```json
{
    "taskListId": "abc123def456",
    "executeCorpId": 100002,
    "executeUserId": 300001,
    "periodStartTime": "2026-01-01 00:00:00",
    "periodEndTime": "2026-12-31 23:59:59"
}
```

**响应参数**：无

**响应示例**：
```json
{
    "code": "200",
    "message": "success"
}
```

---

## 四、任务详情接口

### 4.1 获取任务列表

**接口路径**：`POST /{gateway}/safetyAccountability/taskDetail/list`

**接口描述**：根据清单ID分页查询任务列表

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| pageIndex | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |
| taskListId | String | 是 | 清单表主键ID |
| executeContent | String | 否 | 执行内容（模糊查询） |
| periodStartTime | String | 否 | 任务周期开始时间 |
| periodEndTime | String | 否 | 任务周期结束时间 |
| feedbackCycle | Integer | 否 | 反馈周期：1-每月 2-季度 3-半年 4-年 |
| feedbackStatus | Integer | 否 | 反馈状态：1-正常 2-异常 |
| taskStatus | Integer | 否 | 任务状态：1-进行中 2-已完成 3-已关闭 |

**请求示例**：
```json
{
    "pageIndex": 1,
    "pageSize": 10,
    "taskListId": "abc123def456",
    "executeContent": "检查",
    "feedbackCycle": 1,
    "feedbackStatus": 1,
    "taskStatus": 1
}
```

**响应参数**：

| 参数名                                 | 类型 | 说明 |
|-------------------------------------|------|------|
| id                                  | Long | 主键ID |
| taskDetailId                        | String | 任务详情UUID（业务主键） |
| executeContent                      | String | 执行内容 |
| feedbackCycle                       | Integer | 反馈周期：1-每月 2-季度 3-半年 4-年 |
| feedbackCycleName                   | String | 反馈周期名称 |
| taskScore                           | BigDecimal | 任务分值 |
| taskRating                          | BigDecimal | 当前得分（任务评分） |
| taskStatus                          | Integer | 任务状态：1-进行中 2-已完成 3-已关闭 |
| taskStatusName                      | String | 任务状态名称 |
| feedbackCount                       | Integer | 反馈次数 |
| feedbackStatus                      | Integer | 反馈状态：1-正常 2-存在异常 |
| feedbackStatusName                  | String | 反馈状态名称 |
| currentPeriodFeedback               | Boolean | 当前节点是否反馈 |
| exceptionList                       | Array | 异常列表 |
| exceptionList[].exceptionPeriodFlag | String | 异常周期标识 |
| exceptionList[].exceptionPeriodTime | String | 异常周期 |
| exceptionList[].exceptionType       | Integer | 异常类型：1-未按时反馈 2-反馈内容异常 3-其他 |
| exceptionList[].exceptionTypeName   | String | 异常类型名称 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
            "id": 1,
            "taskDetailId": "detail001",
            "executeContent": "每月提交安全检查报告",
            "feedbackCycle": 1,
            "feedbackCycleName": "每月",
            "taskScore": 10.00,
            "taskRating": 9.50,
            "taskStatus": 1,
            "taskStatusName": "进行中",
            "feedbackCount": 5,
            "feedbackStatus": 1,
            "feedbackStatusName": "正常",
            "currentPeriodFeedback": true,
            "exceptionList": [
                {
                    "exceptionPeriodFlag": "2026-Q1",
                    "exceptionPeriodTime": "2026-01-01 - 2026-01-31",
                    "exceptionType": 1,
                    "exceptionTypeName": "未按时反馈"
                }
            ]
        }
    ],
    "totalCount": 10,
    "pageSize": 10,
    "pageIndex": 1
}
```

---

### 4.2 新增任务

**接口路径**：`POST /{gateway}/safetyAccountability/taskDetail/save`

**接口描述**：新增任务详情（当前清单总分不能超过100）

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskListId | String | 是 | 清单表主键ID |
| executeContent | String | 否 | 执行内容 |
| feedbackCycle | Integer | 是 | 反馈周期：1-每月 2-季度 3-半年 4-年 |
| taskScore | BigDecimal | 否 | 任务分值（当前清单总分不能超过100） |

**请求示例**：
```json
{
    "taskListId": "abc123def456",
    "executeContent": "每月提交安全检查报告",
    "feedbackCycle": 1,
    "taskScore": 10.00
}
```

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| id | Long | 主键ID |
| taskDetailId | String | 任务详情UUID（业务主键） |
| executeContent | String | 执行内容 |
| feedbackCycle | Integer | 反馈周期 |
| feedbackCycleName | String | 反馈周期名称 |
| taskScore | BigDecimal | 任务分值 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": {
        "id": 1,
        "taskDetailId": "detail001",
        "executeContent": "每月提交安全检查报告",
        "feedbackCycle": 1,
        "feedbackCycleName": "每月",
        "taskScore": 10.00
    }
}
```

---

### 4.3 获取任务详情

**接口路径**：`GET /{gateway}/safetyAccountability/taskDetail/{detailId}`

**接口描述**：根据任务ID查询任务详情

**路径参数**：

| 参数名      | 类型     | 必填 | 说明        |
|----------|--------|-----|-----------|
| detailId | String | 是 | 任务表业务主键ID |

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| id | Long | 主键ID |
| taskDetailId | String | 任务详情UUID |
| taskListId | String | 清单表主键ID |
| taskListName | String | 清单名称 |
| taskLevel | Integer | 任务级别：1-企业级 2-部门级 3-班组级 |
| taskLevelName | String | 任务级别名称 |
| responsibilityPost | String | 责任岗位 |
| feedbackCycle | Integer | 反馈周期：1-每月 2-季度 3-半年 4-年 |
| feedbackCycleName | String | 反馈周期名称 |
| taskScore | BigDecimal | 任务分值 |
| executeContent | String | 执行内容 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": {
        "id": 1,
        "taskDetailId": "detail001",
        "taskListId": "abc123def456",
        "taskListName": "2026年度安全生产责任清单",
        "taskLevel": 1,
        "taskLevelName": "企业级",
        "responsibilityPost": "安全员",
        "feedbackCycle": 1,
        "feedbackCycleName": "每月",
        "taskScore": 10.00,
        "executeContent": "每月提交安全检查报告"
    }
}
```

---

### 4.4 关闭任务

**接口路径**：`POST /{gateway}/safetyAccountability/taskDetail/close`

**接口描述**：手动关闭任务

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskDetailId | String | 是 | 任务UUID |

**请求示例**：
```json
{
    "taskDetailId": "detail001"
}
```

**响应参数**：无

**响应示例**：
```json
{
    "code": "200",
    "message": "success"
}
```

---

### 4.5 更新任务评分

**接口路径**：`POST /{gateway}/safetyAccountability/taskDetail/updateScore`

**接口描述**：对任务进行评分

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskDetailId | String | 是 | 任务UUID |
| score | Decimal | 是 | 分数（不能超过任务分值） |

**请求示例**：
```json
{
    "taskDetailId": "detail001",
    "score": 9.50
}
```

**响应参数**：无

**响应示例**：
```json
{
    "code": "200",
    "message": "success"
}
```

---

## 五、反馈接口

### 5.1 提交反馈

**接口路径**：`POST /{gateway}/safetyAccountability/feedback/save`

**接口描述**：执行人提交反馈

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskDetailId | String | 是 | 任务ID |
| taskListId | String | 是 | 清单ID |
| feedbackContent | String | 否 | 反馈内容 |

**请求示例**：
```json
{
    "taskDetailId": "detail001",
    "taskListId": "abc123def456",
    "feedbackContent": "本月已完成安全检查，发现隐患3处，已全部整改完成。"
}
```

**响应参数**：

| 参数名 | 类型     | 说明 |
|-------|--------|------|
| id | Long   | 主键ID |
| feedbackId | String | 反馈UUID（业务主键） |
| feedbackTime | String | 反馈时间 |
| feedbackContent | String | 反馈内容 |
| feedbackUserId | Long   | 反馈人ID |
| feedbackUserName | String | 反馈人名称 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": {
        "id": 1,
        "feedbackId": "feedback001",
        "feedbackTime": "2026-05-15 14:30:00",
        "feedbackContent": "本月已完成安全检查，发现隐患3处，已全部整改完成。",
        "feedbackUserId": 1,
        "feedbackUserName": "张三"
    }
}
```

---

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

**接口路径**：`POST /{gateway}/safetyAccountability/feedback/periodGroupList`

**接口描述**：根据任务ID获取反馈周期分组列表（以周期标识为维度统计）

**请求参数**：

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

**请求示例**：
```json
{
    "taskDetailId": "detail001",
    "feedbackTimeStart": "2026-01-01",
    "feedbackTimeEnd": "2026-12-31"
}
```

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| taskDetailId | String | 是 | 任务ID |
| feedbackPeriodStartTime | String | 反馈周期开始时间 |
| feedbackPeriodEndTime | String | 反馈周期结束时间 |
| feedbackCount | Integer | 反馈次数（以周期标识为维度统计） |
| feedbackUserName | String | 反馈人姓名 |
| feedbackPeriodFlag | String | 周期标识 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
           "taskDetailId": "detail001",
            "feedbackPeriodStartTime": "2026-05-01 00:00:00",
            "feedbackPeriodEndTime": "2026-05-31 23:59:59",
            "feedbackCount": 2,
            "feedbackUserName": "张三",
            "feedbackPeriodFlag": "2026-05"
        },
        {
           "taskDetailId": "detail002",
            "feedbackPeriodStartTime": "2026-04-01 00:00:00",
            "feedbackPeriodEndTime": "2026-04-30 23:59:59",
            "feedbackCount": 1,
            "feedbackUserName": "张三",
            "feedbackPeriodFlag": "2026-04"
        }
    ]
}
```

---

### 5.3 获取反馈列表

**接口路径**：`POST /{gateway}/safetyAccountability/feedback/list`

**接口描述**：根据任务ID和周期标识获取反馈列表

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| taskDetailId | String | 是 | 任务ID |
| feedbackPeriodFlag | String | 是 | 周期标识（如：2026-05、2026-Q1、2026-H1、2026） |

**请求示例**：
```json
{
    "taskDetailId": "detail001",
    "feedbackPeriodFlag": "2026-05"
}
```

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| id | Long | 主键ID |
| feedbackId | String | 反馈UUID |
| feedbackTime | String | 反馈时间 |
| feedbackContent | String | 反馈内容 |
| feedbackUserName | String | 反馈人姓名 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
            "id": 1,
            "feedbackId": "feedback001",
            "feedbackTime": "2026-05-15 14:30:00",
            "feedbackContent": "本月已完成安全检查，发现隐患3处，已全部整改完成。",
            "feedbackUserName": "张三"
        },
        {
            "id": 2,
            "feedbackId": "feedback002",
            "feedbackTime": "2026-05-20 10:15:00",
            "feedbackContent": "补充反馈：隐患已全部验收通过。",
            "feedbackUserName": "张三"
        }
    ]
}
```

---

### 5.4 获取反馈详情

**接口路径**：`GET /{gateway}/safetyAccountability/feedback/{id}`

**接口描述**：根据反馈ID获取反馈详情

**路径参数**：

| 参数名        | 类型     | 必填 | 说明        |
|------------|--------|-----|-----------|
| feedbackId | String | 是 | 反馈表业务主键ID |

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| id | Long | 主键ID |
| feedbackId | String | 反馈UUID |
| taskDetailId | String | 任务详情ID |
| executeContent | String | 执行内容（任务信息） |
| feedbackCycle | Integer | 反馈周期：1-每月 2-季度 3-半年 4-年 |
| feedbackCycleName | String | 反馈周期名称 |
| feedbackContent | String | 反馈内容 |
| feedbackTime | String | 反馈时间 |
| feedbackPeriodStartTime | String | 反馈周期开始时间 |
| feedbackPeriodEndTime | String | 反馈周期结束时间 |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": {
        "id": 1,
        "feedbackId": "feedback001",
        "taskDetailId": "detail001",
        "executeContent": "每月提交安全检查报告",
        "feedbackCycle": 1,
        "feedbackCycleName": "每月",
        "feedbackContent": "本月已完成安全检查，发现隐患3处，已全部整改完成。",
        "feedbackTime": "2026-05-15 14:30:00",
        "feedbackPeriodStartTime": "2026-05-01 00:00:00",
        "feedbackPeriodEndTime": "2026-05-31 23:59:59"
    }
}
```

---

## 六、统计接口

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

**接口路径**：`POST /{gateway}/safetyAccountability/statistics/corpStatistics`

**接口描述**：股份端获取企业统计数据

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| pageIndex | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |
| corpName | String | 否 | 企业名称（模糊查询） |

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

**响应参数**：

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

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
            "corpId": 100001,
            "corpName": "XX分公司",
            "completedTaskCount": 10,
            "closedTaskCount": 2,
            "totalTaskCount": 15
        }
    ],
    "totalCount": 50,
    "pageSize": 10,
    "pageIndex": 1
}
```

---

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

**接口路径**：`POST /{gateway}/safetyAccountability/statistics/evaluationList`

**接口描述**：获取企业评价列表

**请求参数**：

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

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

**响应参数**：

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

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
            "corpId": 100001,
            "corpName": "XX分公司",
            "listCount": 3
        }
    ],
    "totalCount": 50,
    "pageSize": 10,
    "pageIndex": 1
}
```

---

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

**接口路径**：`POST /{gateway}/safetyAccountability/statistics/issueStatistics`

**接口描述**：获取企业任务下发统计数据（以执行公司ID为维度统计）

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| pageIndex | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |
| corpName | String | 否 | 企业名称（模糊查询） |

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

**响应参数**：

| 参数名 | 类型 | 说明 |
|-------|------|------|
| corpId | Long | 公司ID |
| corpName | String | 公司名称 |
| issueCount | Integer | 任务清单下发数（以清单表中的执行公司ID为维度统计） |

**响应示例**：
```json
{
    "code": "200",
    "message": "success",
    "data": [
        {
            "corpId": 100001,
            "corpName": "XX分公司",
            "issueCount": 15
        }
    ],
    "totalCount": 50,
    "pageSize": 10,
    "pageIndex": 1
}
```

---

## 七、反馈周期时间工具类

根据周期标识获取对应的开始时间和结束时间：

| 周期标识 | 开始时间 | 结束时间 | 说明 |
|---------|---------|---------|------|
| 2026-05 | 2026-05-01 00:00:00 | 2026-05-31 23:59:59 | 月 |
| 2026-Q1 | 2026-01-01 00:00:00 | 2026-03-31 23:59:59 | 第一季度 |
| 2026-Q2 | 2026-04-01 00:00:00 | 2026-06-30 23:59:59 | 第二季度 |
| 2026-Q3 | 2026-07-01 00:00:00 | 2026-09-30 23:59:59 | 第三季度 |
| 2026-Q4 | 2026-10-01 00:00:00 | 2026-12-31 23:59:59 | 第四季度 |
| 2026-H1 | 2026-01-01 00:00:00 | 2026-06-30 23:59:59 | 上半年 |
| 2026-H2 | 2026-07-01 00:00:00 | 2026-12-31 23:59:59 | 下半年 |
| 2026 | 2026-01-01 00:00:00 | 2026-12-31 23:59:59 | 年 |

---

## 八、注意事项

1. **任务分值限制**：新增任务时，当前清单下所有任务分值总和不能超过100分。

2. **反馈周期判断**：
   - 每月：每个月必须有反馈，否则判定为异常
   - 每季度：每个季度必须有反馈，否则判定为异常
   - 半年：每半年必须有反馈，否则判定为异常
   - 年：每年必须有反馈，否则判定为异常
   - 周期内可多次提交反馈

3. **状态流转**：
   - 任务清单状态：进行中 → 已完成（周期结束自动变更）/ 已关闭（手动关闭）
   - 任务状态：进行中 → 已完成（周期结束自动变更）/ 已关闭（手动关闭）

4. **反馈状态推导**：清单的反馈状态由任务反馈状态推导，有任意任务反馈状态为异常时，清单反馈状态为异常。

5. **下发条件**：仅可下发开启状态（switchFlag=1）的任务清单。

6. **评分限制**：任务评分不能超过任务分值。