38 KiB

Raw Blame History

安全责任清单接口文档

一、概述

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`	无数据响应	删除、关闭等无返回数据的操作

响应结构示例：

// 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 使用示例：

// 新增 - 返回单条数据
@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-开

请求示例：

{
    "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	清单分数

响应示例：

{
    "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-开

请求示例：

{
    "taskListName": "2026年度安全生产责任清单",
    "taskLevel": 1,
    "responsibilityPost": "安全员",
    "switchFlag": 1
}

响应参数：

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

响应示例：

{
    "code": "200",
    "message": "success",
    "data": {
        "id": 1,
        "taskListId": "abc123def456",
        "taskListName": "2026年度安全生产责任清单",
        "taskLevel": 1,
        "taskLevelName": "企业级"
    }
}

3.3 关闭清单

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

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

请求参数：

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

请求示例：

{
    "taskListId": "abc123def456"
}

响应参数：无

响应示例：

{
    "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）

请求示例：

{
    "taskListId": "abc123def456",
    "executeCorpId": 100002,
    "executeUserId": 300001,
    "periodStartTime": "2026-01-01 00:00:00",
    "periodEndTime": "2026-12-31 23:59:59"
}

响应参数：无

响应示例：

{
    "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-已关闭

请求示例：

{
    "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	异常类型名称

响应示例：

{
    "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）

请求示例：

{
    "taskListId": "abc123def456",
    "executeContent": "每月提交安全检查报告",
    "feedbackCycle": 1,
    "taskScore": 10.00
}

响应参数：

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

响应示例：

{
    "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	执行内容

响应示例：

{
    "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

请求示例：

{
    "taskDetailId": "detail001"
}

响应参数：无

响应示例：

{
    "code": "200",
    "message": "success"
}

4.5 更新任务评分

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

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

请求参数：

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

请求示例：

{
    "taskDetailId": "detail001",
    "score": 9.50
}

响应参数：无

响应示例：

{
    "code": "200",
    "message": "success"
}

五、反馈接口

5.1 提交反馈

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

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

请求参数：

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

请求示例：

{
    "taskDetailId": "detail001",
    "taskListId": "abc123def456",
    "feedbackContent": "本月已完成安全检查，发现隐患3处，已全部整改完成。"
}

响应参数：

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

响应示例：

{
    "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）

请求示例：

{
    "taskDetailId": "detail001",
    "feedbackTimeStart": "2026-01-01",
    "feedbackTimeEnd": "2026-12-31"
}

响应参数：

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

响应示例：

{
    "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）

请求示例：

{
    "taskDetailId": "detail001",
    "feedbackPeriodFlag": "2026-05"
}

响应参数：

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

响应示例：

{
    "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	反馈周期结束时间

响应示例：

{
    "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	否	企业名称（模糊查询）

请求示例：

{
    "pageIndex": 1,
    "pageSize": 10,
    "corpName": "分公司"
}

响应参数：

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

响应示例：

{
    "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-已评分

请求示例：

{
    "pageIndex": 1,
    "pageSize": 10,
    "corpName": "分公司",
    "scoreStatus": 0
}

响应参数：

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

响应示例：

{
    "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	否	企业名称（模糊查询）

请求示例：

{
    "pageIndex": 1,
    "pageSize": 10,
    "corpName": "分公司"
}

响应参数：

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

响应示例：

{
    "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	年

八、注意事项

任务分值限制：新增任务时，当前清单下所有任务分值总和不能超过100分。
反馈周期判断：
- 每月：每个月必须有反馈，否则判定为异常
- 每季度：每个季度必须有反馈，否则判定为异常
- 半年：每半年必须有反馈，否则判定为异常
- 年：每年必须有反馈，否则判定为异常
- 周期内可多次提交反馈
状态流转：
- 任务清单状态：进行中 → 已完成（周期结束自动变更）/ 已关闭（手动关闭）
- 任务状态：进行中 → 已完成（周期结束自动变更）/ 已关闭（手动关闭）
反馈状态推导：清单的反馈状态由任务反馈状态推导，有任意任务反馈状态为异常时，清单反馈状态为异常。
下发条件：仅可下发开启状态（switchFlag=1）的任务清单。
评分限制：任务评分不能超过任务分值。

38 KiB Raw Blame History Unescape Escape

安全责任清单接口文档

一、概述

1.1 项目结构

1.2 模块职责

1.3 命名规范

1.4 响应结构规范

1.5 表清单

二、枚举值说明

2.1 任务级别 (taskLevel)

2.2 任务状态 (status)

2.3 反馈周期 (feedbackCycle)

2.4 反馈状态 (feedbackStatus)

2.5 开关状态 (switchFlag)

2.6 异常类型 (exceptionType)

2.7 评分状态 (scoreStatus)

三、任务清单接口

3.1 获取任务清单列表

3.2 新增任务清单

3.3 关闭清单

3.4 任务下发

四、任务详情接口

4.1 获取任务列表

4.2 新增任务

4.3 获取任务详情

4.4 关闭任务

4.5 更新任务评分

五、反馈接口

5.1 提交反馈

5.2 获取反馈周期分组列表

5.3 获取反馈列表

5.4 获取反馈详情

六、统计接口

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

6.2 获取企业评价列表

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

七、反馈周期时间工具类

八、注意事项

38 KiB

Raw Blame History