# 安全责任清单后端开发文档

## 一、概述

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