docs 补充项目注释

2026-06-01 13:58:13 +08:00
parent 107d3326b4
commit e49f3b2260
94 changed files with 2328 additions and 68 deletions
@@ -19,6 +19,9 @@ public class FlowDefinitionVo implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 流程定义主键
+     */
    private Long id;

    /**
@@ -23,6 +23,9 @@ public class FlowHisTaskVo implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 历史任务主键
+     */
    private Long id;

    /**
@@ -34,7 +34,11 @@ import org.dromara.workflow.service.IFlwNodeExtService;
 import org.dromara.workflow.service.IFlwTaskService;
 import org.springframework.stereotype.Component;

-import java.util.*;
+import java.io.Serial;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;

 /**
 * 工作流全局监听器，处理任务流转中的扩展变量、消息和事件发布。
@@ -48,6 +52,8 @@ import java.util.*;
 public class WorkflowGlobalListener implements GlobalListener {

    private static final String NODE_KEY_SEPARATOR = ":";
+    @Serial
+    private static final long serialVersionUID = -5133036757491932497L;

    private final IFlwTaskService flwTaskService;
    private final IFlwInstanceService flwInstanceService;
@@ -256,6 +262,14 @@ public class WorkflowGlobalListener implements GlobalListener {
        );
    }

+    /**
+     * 判断是否需要发送后续待办消息。
+     *
+     * @param flowParams 流程参数
+     * @param definition 流程定义
+     * @param nextTasks  后续任务列表
+     * @return 是否发送待办消息
+     */
    private boolean shouldSendTaskMessage(FlowParams flowParams, Definition definition, List<Task> nextTasks) {
        if (flowParams == null || !TaskStatusEnum.BACK.getStatus().equals(flowParams.getHisStatus())) {
            return true;
@@ -268,6 +282,14 @@ public class WorkflowGlobalListener implements GlobalListener {
        return !StringUtils.equals(applyNodeCode, nextTasks.get(0).getNodeCode());
    }

+    /**
+     * 在流程完成或退回时通知发起人。
+     *
+     * @param definition 流程定义
+     * @param instance   流程实例
+     * @param status     业务状态
+     * @param variable   流程变量
+     */
    private void notifyInitiatorIfNeeded(Definition definition, Instance instance, String status, Map<String, Object> variable) {
        if (!StringUtils.equalsAny(status, BusinessStatusEnum.FINISH.getStatus(), BusinessStatusEnum.BACK.getStatus())) {
            return;
@@ -24,6 +24,15 @@ import java.util.Map;
 */
 public interface FlwHisTaskMapper extends BaseMapperPlus<FlowHisTask, FlowHisTaskVo>, MPJBaseMapper<FlowHisTask> {

+    /**
+     * 分页查询已办任务列表。
+     *
+     * @param page 分页对象
+     * @param bo 查询条件
+     * @param categoryIds 流程分类 ID 集合
+     * @param userId 当前用户 ID
+     * @return 已办任务分页结果
+     */
    default Page<FlowHisTaskVo> getListFinishTask(Page<FlowHisTaskVo> page, FlowTaskBo bo, List<String> categoryIds, String userId) {
        Map<String, Object> params = bo.getParams();
        return QueryBuilder.lambdaJoin("a", FlowHisTask.class)
@@ -22,6 +22,15 @@ import java.util.Map;
 */
 public interface FlwTaskMapper extends BaseMapperPlus<FlowTask, FlowTaskVo>, MPJBaseMapper<FlowTask> {

+    /**
+     * 分页查询运行中的待办任务。
+     *
+     * @param page 分页对象
+     * @param bo 查询条件
+     * @param categoryIds 流程分类 id 列表
+     * @param userId 当前用户 id
+     * @return 待办任务分页结果
+     */
    default Page<FlowTaskVo> getListRunTask(Page<FlowTaskVo> page, FlowTaskBo bo, List<String> categoryIds, String userId) {
        Map<String, Object> params = bo.getParams();
        return QueryBuilder.lambdaJoin("t", FlowTask.class)
@@ -54,6 +63,15 @@ public interface FlwTaskMapper extends BaseMapperPlus<FlowTask, FlowTaskVo>, MPJ
            .page(page, FlowTaskVo.class);
    }

+    /**
+     * 分页查询抄送任务。
+     *
+     * @param page 分页对象
+     * @param bo 查询条件
+     * @param categoryIds 流程分类 id 列表
+     * @param userId 当前用户 id
+     * @return 抄送任务分页结果
+     */
    default Page<FlowTaskVo> getTaskCopyByPage(Page<FlowTaskVo> page, FlowTaskBo bo, List<String> categoryIds, String userId) {
        Map<String, Object> params = bo.getParams();
        return QueryBuilder.lambdaJoin("a", FlowUser.class)
@@ -89,6 +89,14 @@ public class FlwCommonServiceImpl implements IFlwCommonService {
        sendMessage(messageType, message, subject, userList, null);
    }

+    /**
+     * 发送流程结果通知。
+     *
+     * @param flowName    流程名称
+     * @param status      业务状态
+     * @param messageType 消息类型列表
+     * @param userList    接收用户列表
+     */
    @Override
    public void sendResultMessage(String flowName, BusinessStatusEnum status, List<String> messageType, List<UserDTO> userList) {
        if (status == null || CollUtil.isEmpty(messageType) || CollUtil.isEmpty(userList)) {
@@ -99,6 +107,15 @@ public class FlwCommonServiceImpl implements IFlwCommonService {
        sendMessage(messageType, message, DEFAULT_SUBJECT, userList, PATH_MY_DOCUMENT);
    }

+    /**
+     * 发送消息给指定用户列表。
+     *
+     * @param messageType 消息类型列表
+     * @param message     消息内容
+     * @param subject     邮件标题
+     * @param userList    接收用户列表
+     * @param path        前端跳转路径
+     */
    @Override
    public void sendMessage(List<String> messageType, String message, String subject, List<UserDTO> userList, String path) {
        if (CollUtil.isEmpty(messageType) || CollUtil.isEmpty(userList)) {
@@ -114,6 +131,17 @@ public class FlwCommonServiceImpl implements IFlwCommonService {
        ThreadUtils.virtualInvokeAll(sendTasks);
    }

+    /**
+     * 按消息类型执行具体发送逻辑。
+     *
+     * @param code      消息类型编码
+     * @param message   消息内容
+     * @param subject   邮件标题
+     * @param path      前端跳转路径
+     * @param userIds   接收用户 id 列表
+     * @param emails    接收邮箱集合
+     * @param userCount 接收用户数量
+     */
    private void sendMessageByType(String code, String message, String subject, String path, List<Long> userIds, Set<String> emails, int userCount) {
        MessageTypeEnum messageTypeEnum = MessageTypeEnum.getByCode(code);
        if (ObjectUtil.isEmpty(messageTypeEnum)) {
@@ -273,6 +273,11 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
    }


+    /**
+     * 校验当前用户是否有权限删除流程实例，并发布删除事件。
+     *
+     * @param flowInstances 待删除流程实例列表
+     */
    private void processDeleteHandler(List<FlowInstance> flowInstances) {

        String userId = LoginHelper.getUserIdStr();
@@ -120,7 +120,7 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
    /**
     * 根据办理人类型查询右侧候选数据。
     *
-     * @param type 办理人类型
+     * @param type      办理人类型
     * @param taskQuery 查询条件
     * @return 办理人数据
     */
@@ -180,7 +180,7 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
    /**
     * 构建设计器右侧办理人列表数据。
     *
-     * @param dto 办理人数据
+     * @param dto  办理人数据
     * @param type 办理人类型
     * @return 办理人列表构建器
     */
@@ -218,6 +218,12 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
            .toList();
    }

+    /**
+     * 按任务分配类型批量查询用户。
+     *
+     * @param typeIdMap 任务分配类型与 id 列表映射
+     * @return 用户列表
+     */
    private List<UserDTO> getUsersByTypes(Map<TaskAssigneeEnum, List<String>> typeIdMap) {
        return typeIdMap.entrySet().stream()
            .map(entry -> this.getUsersByType(entry.getKey(), entry.getValue()))
@@ -226,6 +232,12 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
            .toList();
    }

+    /**
+     * 按任务分配类型批量查询名称映射。
+     *
+     * @param typeIdMap 任务分配类型与 id 列表映射
+     * @return 任务分配类型与名称映射
+     */
    private Map<TaskAssigneeEnum, Map<String, String>> getNamesByTypes(Map<TaskAssigneeEnum, List<String>> typeIdMap) {
        Map<TaskAssigneeEnum, Map<String, String>> nameMap = new EnumMap<>(TaskAssigneeEnum.class);
        typeIdMap.forEach((type, ids) -> nameMap.put(type, this.getNamesByType(type, ids)));