zcloud_gbs_safetyDutyList/docs/安全责任清单后端开发文档.md

384 lines
17 KiB
Markdown
Raw Permalink Normal View History

2026-05-21 14:12:22 +08:00
# 安全责任清单后端开发文档
## 一、概述
### 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 | 客户端层,包含 DTOCmd、Qry和 COClient 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` |
---
## 二、数据库表结构
### 2.1 表清单
| 序号 | 表名 | 表中文名 |
|-----|------|---------|
| 1 | safety_accountability_task_list | 任务清单表 |
| 2 | safety_accountability_task_detail | 任务清单详细表 |
| 3 | safety_accountability_feedback | 执行反馈表 |
| 4 | safety_accountability_feedback_exception | 反馈异常信息表 |
### 2.2 完整建表 SQL
```sql
-- =============================================
-- 任务清单表
-- =============================================
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` varchar(20) DEFAULT NULL COMMENT '异常周期标识',
`feedback_exception_period_time` varchar(20) 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='反馈异常信息表';
```
---
## 三、枚举定义
### 3.1 任务级别枚举 (TaskLevelEnum)
```java
package com.zcloud.safety.accountability.list.domain.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 任务级别枚举
*/
@Getter
@AllArgsConstructor
public enum TaskLevelEnum {
ENTERPRISE(1, "企业级"),
DEPARTMENT(2, "部门级"),
TEAM(3, "班组级");
private final Integer code;
private final String desc;
public static TaskLevelEnum getByCode(Integer code) {
for (TaskLevelEnum e : values()) {
if (e.getCode().equals(code)) {
return e;
}
}
return null;
}
}
```
### 3.2 任务状态枚举 (TaskStatusEnum)
```java
package com.zcloud.safety.accountability.list.domain.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 任务状态枚举
*/
@Getter
@AllArgsConstructor
public enum TaskStatusEnum {
IN_PROGRESS(1, "进行中"),
COMPLETED(2, "已完成"),
CLOSED(3, "已关闭");
private final Integer code;
private final String desc;
public static TaskStatusEnum getByCode(Integer code) {
for (TaskStatusEnum e : values()) {
if (e.getCode().equals(code)) {
return e;
}
}
return null;
}
}
```
### 3.3 反馈周期枚举 (FeedbackCycleEnum)
```java
package com.zcloud.safety.accountability.list.domain.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 反馈周期枚举
*/
@Getter
@AllArgsConstructor
public enum FeedbackCycleEnum {
MONTHLY(1, "每月"),
QUARTERLY(2, "每季度"),
HALF_YEARLY(3, "半年"),
YEARLY(4, "年");
private final Integer code;
private final String desc;
public static FeedbackCycleEnum getByCode(Integer code) {
for (FeedbackCycleEnum e : values()) {
if (e.getCode().equals(code)) {
return e;
}
}
return null;
}
}
```
### 3.4 反馈周期时间工具类
比如 传入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-H1 获取到开始时间2026-01-01 00:00:00结束时间2026-06-30 23:59:59
传入2026-Y 获取到开始时间2026-01-01 00:00:00结束时间2026-12-31 23:59:59
## 四、接口描述
1.获取任务清单列表
可传参公司id
筛选条件:清单名称,任务级别,反馈状态,是否开启(开启或禁用 0关1开
列表展示:清单名称,任务级别,责任岗位,状态(是否启用),执行部门,执行人员,任务数,执行周期,任务状态,反馈状态(由任务状态推导,有任务的反馈状态为异常时则为异常其他为正常),评分人员部门,评分人员,清单分数
2.新增任务清单:
传参:清单名称,任务级别,责任岗位,是否启用
3.获取任务列表
传参清单表主键id筛选条件执行内容任务周期开始时间任务周期结束时间反馈周期反馈状态任务状态
列表展示:执行内容,反馈周期,任务分值,当前得分,任务状态,反馈次数,反馈状态,当前节点是否反馈(按反馈周期划分时间筛选反馈表),异常列表(反馈周期,异常类型)
4.新增任务
传参清单表主键id执行内容反馈周期任务分值实现代码时这一部分要判断当前清单总分不饿能高于100
5.获取任务详情
传参任务表主键id
响应清单表主键id清单名称任务级别责任岗位反馈周期任务分值
6.股份端:获取企业统计
筛选:企业名称
响应:公司名称,执行情况(已完成+已关闭任务数/年度执行任务总数)
7.获取反馈周期分组列表
传参任务id
筛选:反馈时间:开始时间-结束时间
列表展示:反馈周期(反馈周期开始时间-反馈周期结束时间),反馈次数(以周期标识为维度统计一个标识有多少记录),反馈人,周期标识
8.获取反馈列表
传参任务id周期标识
列表展示:反馈时间,反馈内容,反馈人
9.获取反馈详情
传参反馈表id
响应:任务信息(执行内容,反馈周期),反馈信息(反馈内容,反馈时间)
10.获取企业评价列表
筛选:企业名称
传参评分状态0未评分1已评分
响应企业名称待评分清单数量清单表分数为0或空的已评分清单数量清单表分数部位0或不是空的
11.更新任务评分
传参任务id分数
12.提交反馈
传参任务id反馈内容
13.获取企业任务下发统计数
筛选:企业名称
列表展示公司名称任务清单下发数以清单表中的执行公司id为维度统计计数
14.关闭任务
传参任务id
15.关闭清单
传参清单id
16.任务下发
传参清单id开启状态的列表执行公司id执行人员id执行周期开始日期执行周期结束日期