17 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`

二、数据库表结构

2.1 表清单

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

2.2 完整建表 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)

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)

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)

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，执行周期开始日期，执行周期结束日期

17 KiB Raw Blame History Unescape Escape