384 lines
17 KiB
Markdown
384 lines
17 KiB
Markdown
# 安全责任清单后端开发文档
|
||
|
||
## 一、概述
|
||
|
||
### 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` |
|
||
|
||
---
|
||
|
||
## 二、数据库表结构
|
||
|
||
### 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，执行周期开始日期，执行周期结束日期 |