【功能优化】工作流：流程详情的重构 60%：参考钉钉，加签审批后，也成为独立节点

YunaiV
1 parent 758d59d7
Showing 9 changed files with 34 additions and 125 deletions
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/task/vo/instance/BpmApprovalDetailReqVO.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/task/vo/instance/BpmApprovalDetailRespVO.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/listener/BpmTaskEventListener.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmActivityService.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmActivityServiceImpl.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmProcessInstanceServiceImpl.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmTaskService.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/BpmTaskServiceImpl.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/task/bo/AlreadyRunApproveNodeRespBO.java
@@ -15,12 +15,12 @@ public class BpmApprovalDetailReqVO {
     @Schema(description = "流程定义的编号", example = "1024")
     private String processDefinitionId; // 使用场景：发起流程时，传流程定义 ID
+    @Schema(description = "流程变量")
+    private Map<String, Object> processVariables; // 使用场景：同 processDefinitionId，用于流程预测
+
     @Schema(description = "流程实例的编号", example = "1024")
     private String processInstanceId;  // 使用场景：流程已发起时候传流程实例 ID
-    @Schema(description = "流程变量")
-    private Map<String, Object> processVariable; // 使用场景：同 processDefinitionId，用于流程预测
-
     // TODO @芋艿：如果未来 BPMN 增加流程图，它没有发起人节点，会有问题。
     @Schema(description = "流程活动编号", example = "StartUserNode")
     private String activityId; // 用于获取表单权限。1）发起流程时，传“发起人节点” activityId 可获取发起人的表单权限；2）从抄送列表界面进来时，传抄送的 activityId 可获取抄送人的表单权限；
@@ -20,7 +20,7 @@ public class BpmApprovalDetailRespVO {
     private Integer status; // 参见 BpmProcessInstanceStatusEnum 枚举
     @Schema(description = "审批信息列表", requiredMode = Schema.RequiredMode.REQUIRED)
-    private List<ApprovalNodeInfo> approveNodes;
+    private List<NodeInfo> approveNodes;
     @Schema(description = "表单字段权限")
     private Map<String, String> formFieldsPermission;
@@ -40,7 +40,7 @@ public class BpmApprovalDetailRespVO {
     @Schema(description = "审批节点信息")
     @Data
-    public static class ApprovalNodeInfo {
+    public static class NodeInfo {
         @Schema(description = "节点编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "StartUserNode")
         private String id;
@@ -62,8 +62,12 @@ public class BpmApprovalDetailRespVO {
         @Schema(description = "审批节点的任务信息")
         private List<ApprovalTaskInfo> tasks;
+        @Schema(description = "候选人用户 ID 列表", requiredMode = Schema.RequiredMode.NOT_REQUIRED, example = "1818")
+        @JsonIgnore // 不返回，只是方便后续读取，赋值给 candidateUsers
+        private List<Long> candidateUserIds;
+
         @Schema(description = "候选人用户列表")
-        private List<UserSimpleBaseVO> candidateUsers; // 用于未运行任务节点
+        private List<UserSimpleBaseVO> candidateUsers; // 只包含未生成 ApprovalTaskInfo 的用户列表
     }
@@ -8,7 +8,6 @@ import cn.iocoder.yudao.module.bpm.enums.definition.BpmBoundaryEventType;
 import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants;
 import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.BpmnModelUtils;
 import cn.iocoder.yudao.module.bpm.service.definition.BpmModelService;
-import cn.iocoder.yudao.module.bpm.service.task.BpmActivityService;
 import cn.iocoder.yudao.module.bpm.service.task.BpmTaskService;
 import com.google.common.collect.ImmutableSet;
 import jakarta.annotation.Resource;
@@ -44,9 +43,6 @@ public class BpmTaskEventListener extends AbstractFlowableEngineEventListener {
     @Resource
     @Lazy // 解决循环依赖
     private BpmTaskService taskService;
-    @Resource
-    @Lazy // 解决循环依赖
-    private BpmActivityService activityService;
     public static final Set<FlowableEngineEventType> TASK_EVENTS = ImmutableSet.<FlowableEngineEventType>builder()
             .add(FlowableEngineEventType.TASK_CREATED)
@@ -72,7 +68,7 @@ public class BpmTaskEventListener extends AbstractFlowableEngineEventListener {
     @Override
     protected void activityCancelled(FlowableActivityCancelledEvent event) {
-        List<HistoricActivityInstance> activityList = activityService.getHistoricActivityListByExecutionId(event.getExecutionId());
+        List<HistoricActivityInstance> activityList = taskService.getHistoricActivityListByExecutionId(event.getExecutionId());
         if (CollUtil.isEmpty(activityList)) {
             log.error("[activityCancelled][使用 executionId({}) 查找不到对应的活动实例]", event.getExecutionId());
             return;
-package cn.iocoder.yudao.module.bpm.service.task;
-
-import org.flowable.engine.history.HistoricActivityInstance;
-
-import java.util.List;
-
-/**
- * BPM 活动实例 Service 接口
- *
- * @author 芋道源码
- */
-public interface BpmActivityService {
-
-    /**
-     * 获得指定流程实例的活动实例列表
-     *
-     * @param processInstanceId 流程实例的编号
-     * @return 活动实例列表
-     */
-    List<HistoricActivityInstance> getActivityListByProcessInstanceId(String processInstanceId);
-
-    /**
-     * 获得执行编号对应的活动实例
-     *
-     * @param executionId 执行编号
-     * @return 活动实例
-     */
-    List<HistoricActivityInstance> getHistoricActivityListByExecutionId(String executionId);
-
-}
-package cn.iocoder.yudao.module.bpm.service.task;
-
-import jakarta.annotation.Resource;
-import lombok.extern.slf4j.Slf4j;
-import org.flowable.engine.HistoryService;
-import org.flowable.engine.history.HistoricActivityInstance;
-import org.springframework.stereotype.Service;
-import org.springframework.validation.annotation.Validated;
-
-import java.util.List;
-
-// TODO 芋艿：准备废弃
-/**
- * BPM 活动实例 Service 实现类
- *
- * @author 芋道源码
- */
-@Service
-@Slf4j
-@Validated
-public class BpmActivityServiceImpl implements BpmActivityService {
-
-    @Resource
-    private HistoryService historyService;
-
-    @Override
-    public List<HistoricActivityInstance> getActivityListByProcessInstanceId(String processInstanceId) {
-        return historyService.createHistoricActivityInstanceQuery().processInstanceId(processInstanceId)
-                .orderByHistoricActivityInstanceStartTime().asc().list();
-    }
-
-    @Override
-    public List<HistoricActivityInstance> getHistoricActivityListByExecutionId(String executionId) {
-        return historyService.createHistoricActivityInstanceQuery().executionId(executionId).list();
-    }
-
-}
-package cn.iocoder.yudao.module.bpm.service.task;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.collection.ListUtil;
import cn.hutool.core.lang.Assert;
import cn.hutool.core.util.ArrayUtil;
import cn.hutool.core.util.ObjectUtil;
import cn.hutool.core.util.StrUtil;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.common.util.collection.CollectionUtils;
import cn.iocoder.yudao.framework.common.util.collection.SetUtils;
import cn.iocoder.yudao.framework.common.util.date.DateUtils;
import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
import cn.iocoder.yudao.framework.common.util.number.NumberUtils;
import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
import cn.iocoder.yudao.framework.common.util.object.PageUtils;
import cn.iocoder.yudao.module.bpm.api.task.dto.BpmProcessInstanceCreateReqDTO;
import cn.iocoder.yudao.module.bpm.controller.admin.base.user.UserSimpleBaseVO;
import cn.iocoder.yudao.module.bpm.controller.admin.definition.vo.model.simple.BpmSimpleModelNodeVO;
import cn.iocoder.yudao.module.bpm.controller.admin.definition.vo.process.BpmProcessDefinitionRespVO;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.*;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmApprovalDetailRespVO.ApprovalTaskInfo;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.task.BpmTaskRespVO;
import cn.iocoder.yudao.module.bpm.convert.definition.BpmProcessDefinitionConvert;
import cn.iocoder.yudao.module.bpm.convert.task.BpmProcessInstanceConvert;
import cn.iocoder.yudao.module.bpm.dal.dataobject.definition.BpmProcessDefinitionInfoDO;
import cn.iocoder.yudao.module.bpm.enums.ErrorCodeConstants;
import cn.iocoder.yudao.module.bpm.enums.definition.BpmModelTypeEnum;
import cn.iocoder.yudao.module.bpm.enums.definition.BpmSimpleModelNodeType;
import cn.iocoder.yudao.module.bpm.enums.task.BpmProcessInstanceStatusEnum;
import cn.iocoder.yudao.module.bpm.enums.task.BpmReasonEnum;
import cn.iocoder.yudao.module.bpm.enums.task.BpmTaskStatusEnum;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.BpmTaskCandidateInvoker;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.BpmTaskCandidateStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.strategy.BpmTaskCandidateStartUserSelectStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnVariableConstants;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.event.BpmProcessInstanceEventPublisher;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.BpmnModelUtils;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.FlowableUtils;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.SimpleModelUtils;
import cn.iocoder.yudao.module.bpm.service.definition.BpmProcessDefinitionService;
import cn.iocoder.yudao.module.bpm.service.message.BpmMessageService;
import cn.iocoder.yudao.module.system.api.dept.DeptApi;
import cn.iocoder.yudao.module.system.api.dept.dto.DeptRespDTO;
import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
import cn.iocoder.yudao.module.system.api.user.dto.AdminUserRespDTO;
import jakarta.annotation.Resource;
import jakarta.validation.Valid;
import lombok.extern.slf4j.Slf4j;
import org.flowable.bpmn.constants.BpmnXMLConstants;
import org.flowable.bpmn.model.BpmnModel;
import org.flowable.bpmn.model.EndEvent;
import org.flowable.bpmn.model.FlowElement;
import org.flowable.bpmn.model.UserTask;
import org.flowable.engine.HistoryService;
import org.flowable.engine.RuntimeService;
import org.flowable.engine.history.HistoricActivityInstance;
import org.flowable.engine.history.HistoricProcessInstance;
import org.flowable.engine.history.HistoricProcessInstanceQuery;
import org.flowable.engine.repository.ProcessDefinition;
import org.flowable.engine.runtime.ProcessInstance;
import org.flowable.task.api.history.HistoricTaskInstance;
import org.springframework.context.annotation.Lazy;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.validation.annotation.Validated;

import java.util.*;

import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.*;
import static cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmApprovalDetailRespVO.ApprovalNodeInfo;
import static cn.iocoder.yudao.module.bpm.convert.task.BpmProcessInstanceConvert.INSTANCE;
import static cn.iocoder.yudao.module.bpm.enums.ErrorCodeConstants.*;
import static cn.iocoder.yudao.module.bpm.enums.definition.BpmSimpleModelNodeType.*;
import static cn.iocoder.yudao.module.bpm.enums.task.BpmTaskStatusEnum.NOT_START;
import static cn.iocoder.yudao.module.bpm.enums.task.BpmTaskStatusEnum.RUNNING;
import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmTaskCandidateStrategyEnum.START_USER;
import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants.START_USER_NODE_ID;
import static java.util.Arrays.asList;
import static org.flowable.bpmn.constants.BpmnXMLConstants.ELEMENT_EVENT_END;
import static org.flowable.bpmn.constants.BpmnXMLConstants.ELEMENT_TASK_USER;

/**
 * 流程实例 Service 实现类
 * <p>
 * ProcessDefinition & ProcessInstance & Execution & Task 的关系：
 * 1. <a href="https://blog.csdn.net/bobozai86/article/details/105210414" />
 * <p>
 * HistoricProcessInstance & ProcessInstance 的关系：
 * 1. <a href=" https://my.oschina.net/843294669/blog/71902" />
 * <p>
 * 简单来说，前者 = 历史 + 运行中的流程实例，后者仅是运行中的流程实例
 *
 * @author 芋道源码
 */
@Service
@Validated
@Slf4j
public class BpmProcessInstanceServiceImpl implements BpmProcessInstanceService {

    @Resource
    private RuntimeService runtimeService;
    @Resource
    private HistoryService historyService;

    @Resource
    private BpmActivityService activityService;
    @Resource
    private BpmProcessDefinitionService processDefinitionService;
    @Resource
    @Lazy // 避免循环依赖
    private BpmTaskService taskService;
    @Resource
    private BpmMessageService messageService;
    @Resource
    private BpmTaskCandidateInvoker bpmTaskCandidateInvoker;

    @Resource
    private AdminUserApi adminUserApi;
    @Resource
    private DeptApi deptApi;

    @Resource
    private BpmProcessInstanceEventPublisher processInstanceEventPublisher;

    // ========== Query 查询相关方法 ==========

    @Override
    public ProcessInstance getProcessInstance(String id) {
        return runtimeService.createProcessInstanceQuery()
                .includeProcessVariables()
                .processInstanceId(id)
                .singleResult();
    }

    @Override
    public List<ProcessInstance> getProcessInstances(Set<String> ids) {
        return runtimeService.createProcessInstanceQuery().processInstanceIds(ids).list();
    }

    @Override
    public HistoricProcessInstance getHistoricProcessInstance(String id) {
        return historyService.createHistoricProcessInstanceQuery().processInstanceId(id).includeProcessVariables().singleResult();
    }

    @Override
    public List<HistoricProcessInstance> getHistoricProcessInstances(Set<String> ids) {
        return historyService.createHistoricProcessInstanceQuery().processInstanceIds(ids).list();
    }

    @Override
    public PageResult<HistoricProcessInstance> getProcessInstancePage(Long userId,
                                                                      BpmProcessInstancePageReqVO pageReqVO) {
        // 通过 BpmProcessInstanceExtDO 表，先查询到对应的分页
        HistoricProcessInstanceQuery processInstanceQuery = historyService.createHistoricProcessInstanceQuery()
                .includeProcessVariables()
                .processInstanceTenantId(FlowableUtils.getTenantId())
                .orderByProcessInstanceStartTime().desc();
        if (userId != null) { // 【我的流程】菜单时，需要传递该字段
            processInstanceQuery.startedBy(String.valueOf(userId));
        } else if (pageReqVO.getStartUserId() != null) { // 【管理流程】菜单时，才会传递该字段
            processInstanceQuery.startedBy(String.valueOf(pageReqVO.getStartUserId()));
        }
        if (StrUtil.isNotEmpty(pageReqVO.getName())) {
            processInstanceQuery.processInstanceNameLike("%" + pageReqVO.getName() + "%");
        }
        if (StrUtil.isNotEmpty(pageReqVO.getProcessDefinitionKey())) {
            processInstanceQuery.processDefinitionKey(pageReqVO.getProcessDefinitionKey());
        }
        if (StrUtil.isNotEmpty(pageReqVO.getCategory())) {
            processInstanceQuery.processDefinitionCategory(pageReqVO.getCategory());
        }
        if (pageReqVO.getStatus() != null) {
            processInstanceQuery.variableValueEquals(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS, pageReqVO.getStatus());
        }
        if (ArrayUtil.isNotEmpty(pageReqVO.getCreateTime())) {
            processInstanceQuery.startedAfter(DateUtils.of(pageReqVO.getCreateTime()[0]));
            processInstanceQuery.startedBefore(DateUtils.of(pageReqVO.getCreateTime()[1]));
        }
        // 查询数量
        long processInstanceCount = processInstanceQuery.count();
        if (processInstanceCount == 0) {
            return PageResult.empty(processInstanceCount);
        }
        // 查询列表
        List<HistoricProcessInstance> processInstanceList = processInstanceQuery.listPage(PageUtils.getStart(pageReqVO), pageReqVO.getPageSize());
        return new PageResult<>(processInstanceList, processInstanceCount);
    }


    private Map<String, String> getFormFieldsPermission(BpmnModel bpmnModel,
                                                        String activityId, String taskId) {
        // 1. 获取流程活动编号。流程活动 Id 为空事，从流程任务中获取流程活动 Id
        if (StrUtil.isEmpty(activityId) && StrUtil.isNotEmpty(taskId)) {
            activityId = Optional.ofNullable(taskService.getHistoricTask(taskId))
                    .map(HistoricTaskInstance::getTaskDefinitionKey).orElse(null);
        }
        if (StrUtil.isEmpty(activityId)) {
            return null;
        }

        // 2. 从 BpmnModel 中解析表单字段权限
        return BpmnModelUtils.parseFormFieldsPermission(bpmnModel, activityId);
    }

    @Override
    public BpmApprovalDetailRespVO getApprovalDetail(Long loginUserId, BpmApprovalDetailReqVO reqVO) {
        // 1. 设置流程未发起的值
        Long startUserId; // 流程发起人
        HistoricProcessInstance historicProcessInstance = null;
        ProcessInstance processInstance = null; // 流程
        Integer processInstanceStatus; // 流程状态
        ProcessDefinition processDefinition = null; // 流程定义
        Map<String, Object> processVariable; // 流程变量
        // 1.4 以下是用于流程预测的值
        List<ApprovalNodeInfo> endApprovalNodeInfos = new ArrayList<>(); // 已结束的审批信息
        List<ApprovalNodeInfo> runningApprovalNodeInfos = new ArrayList<>(); // 进行中的审批信息
        BpmnModel bpmnModel;
        List<HistoricActivityInstance> activities = null;
        List<HistoricTaskInstance> tasks = null;
        // 2 设置流程已发起的值
        if (reqVO.getProcessInstanceId() != null) {
            // 校验流程存在
            historicProcessInstance = getHistoricProcessInstance(reqVO.getProcessInstanceId());
            if (historicProcessInstance == null) {
                throw exception(ErrorCodeConstants.PROCESS_INSTANCE_NOT_EXISTS);
            }
            processInstance = getProcessInstance(historicProcessInstance.getId());
            processDefinition = processDefinitionService.getProcessDefinition(historicProcessInstance.getProcessDefinitionId());
            bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processDefinition.getId());

            startUserId = Long.valueOf(historicProcessInstance.getStartUserId());
            processInstanceStatus = FlowableUtils.getProcessInstanceStatus(historicProcessInstance);
            processVariable = historicProcessInstance.getProcessVariables();

            // 2.4 以下是用于流程预测的值
            activities = activityService.getActivityListByProcessInstanceId(historicProcessInstance.getId());
            tasks = taskService.getTaskListByProcessInstanceId(reqVO.getProcessInstanceId(), true);
            endApprovalNodeInfos = getEndApprovalNodeInfoList(startUserId, processInstanceStatus, activities, tasks);
            runningApprovalNodeInfos = getRunApproveNodeList(activities, tasks, bpmnModel, startUserId, processInstance);
        } else {
            processDefinition = processDefinitionService.getProcessDefinition(reqVO.getProcessDefinitionId());
            bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processDefinition.getId());
            processInstanceStatus = BpmProcessInstanceStatusEnum.NOT_START.getStatus();
            startUserId = loginUserId;
            processVariable = reqVO.getProcessVariable();
        }

        // 3. 流程定义
        BpmProcessDefinitionInfoDO processDefinitionInfo = processDefinitionService.getProcessDefinitionInfo(processDefinition.getId());

        // 流程已经结束，直接 return，无需预测
        if (BpmProcessInstanceStatusEnum.isProcessEndStatus(processInstanceStatus)) {
            return buildApprovalDetail(processInstanceStatus, bpmnModel, historicProcessInstance, processDefinition, processDefinitionInfo, reqVO,
                    endApprovalNodeInfos, runningApprovalNodeInfos, null, null);
        }

        // 5 .登录用户的待办任务
        // TODO @jason：有一个极端情况，如果一个用户有 2 个 task A 和 B，A 已经通过，B 需要审核。这个时，通过 A 进来，todo 拿到 B，会不会表单权限不一致哈。
        // 目前的想法，是不是不依赖前端传递参数。而是后端推导，按照一个顺序。待审批 》 taskId/activityId
        BpmTaskRespVO todoTask = taskService.getFirstTodoTask(loginUserId, reqVO.getProcessInstanceId());

        // 6，预测未运行节点的审批信息。需要区分 BPMN 设计器 和 SIMPLE 设计器
        List<ApprovalNodeInfo> simulateApprovalNodeInfos = getSimulateApproveNodeList(processDefinitionInfo, processInstance, bpmnModel, startUserId, processVariable,
                activities);
        return buildApprovalDetail(processInstanceStatus, bpmnModel, historicProcessInstance, processDefinition, processDefinitionInfo, reqVO,
                endApprovalNodeInfos, runningApprovalNodeInfos, simulateApprovalNodeInfos, todoTask);
    }

    private BpmApprovalDetailRespVO buildApprovalDetail(Integer processInstanceStatus,
                                                        BpmnModel bpmnModel,
                                                        HistoricProcessInstance processInstance,
                                                        ProcessDefinition processDefinition,
                                                        BpmProcessDefinitionInfoDO processDefinitionInfo,
                                                        BpmApprovalDetailReqVO reqVO,
                                                        List<ApprovalNodeInfo> endApprovalNodeInfos,
                                                        List<ApprovalNodeInfo> runningApprovalNodeInfos,
                                                        List<ApprovalNodeInfo> simulateApprovalNodeInfos,
                                                        BpmTaskRespVO todoTask) {
        BpmProcessInstanceRespVO processInstanceResp = null;
        if (processInstance != null) {
            AdminUserRespDTO startUser = adminUserApi.getUser(NumberUtils.parseLong(processInstance.getStartUserId()));
            DeptRespDTO dept = null;
            if (startUser != null && startUser.getDeptId() != null) {
                dept = deptApi.getDept(startUser.getDeptId());
            }
            processInstanceResp = INSTANCE.buildProcessInstance(processInstance, null,
                    null, startUser, dept);
        }
        List<UserTask> userTaskList = BpmTaskCandidateStartUserSelectStrategy.getStartUserSelectUserTaskList(bpmnModel);
        BpmProcessDefinitionRespVO definitionResp = BpmProcessDefinitionConvert.INSTANCE.buildProcessDefinition(
                processDefinition, null, processDefinitionInfo, null, null, bpmnModel, userTaskList
        );

        // 4. 表单权限
        Map<String, String> formFieldsPermission = getFormFieldsPermission(bpmnModel, reqVO.getActivityId(), reqVO.getTaskId());
        return new BpmApprovalDetailRespVO().setStatus(processInstanceStatus)
                .setProcessDefinition(definitionResp)
                .setProcessInstance(processInstanceResp)
                .setFormFieldsPermission(formFieldsPermission)
                .setTodoTask(todoTask)
                .setApproveNodes(CollectionUtils.newArrayList(asList(endApprovalNodeInfos, runningApprovalNodeInfos, simulateApprovalNodeInfos)));
    }

    private List<ApprovalNodeInfo> getEndApprovalNodeInfoList(Long startUserId,
                                                              Integer processInstanceStatus,
                                                              List<HistoricActivityInstance> activities,
                                                              List<HistoricTaskInstance> tasks) {
        // 获取已运行的任务(包括运行中的任务)
        Map<String, HistoricTaskInstance> taskMap = convertMap(tasks, HistoricTaskInstance::getId);
        Map<String, List<HistoricTaskInstance>> addSignTaskMap = convertMultiMap(
                filterList(tasks, task -> StrUtil.isNotEmpty(task.getParentTaskId())), HistoricTaskInstance::getParentTaskId);

        // 遍历 activities 列表，只处理已结束的节点
        List<HistoricActivityInstance> endActivities = filterList(activities, activity -> activity.getEndTime() != null
                        && (StrUtil.equalsAny(activity.getActivityType(), ELEMENT_TASK_USER, ELEMENT_EVENT_END)));
        List<ApprovalNodeInfo> approvalNodes = convertList(endActivities, activity -> {
            ApprovalNodeInfo approvalNodeInfo = new ApprovalNodeInfo().setId(activity.getId()).setName(activity.getActivityName())
                    .setStartTime(DateUtils.of(activity.getStartTime())).setEndTime(DateUtils.of(activity.getEndTime()));
            // 用户任务
            if (ELEMENT_TASK_USER.equals(activity.getActivityType())) {
                // nodeType
                approvalNodeInfo.setNodeType(START_USER_NODE_ID.equals(activity.getActivityId()) ?
                        START_USER_NODE.getType() : APPROVE_NODE.getType());
                HistoricTaskInstance task = taskMap.get(activity.getTaskId());
                // tasks
                ApprovalTaskInfo approveTask = BpmProcessInstanceConvert.INSTANCE.buildApprovalTaskInfo(task);
                List<ApprovalTaskInfo> approveTasks = CollUtil.newArrayList(approveTask);
                // TODO @jason：会有加签任务的加签，A 加 B，B 加 C，C 加 D 这种；最好么，477 到 480 这种，和 510 到 513 这种，封装个小方法。
                List<HistoricTaskInstance> addSignTasks = addSignTaskMap.get(activity.getTaskId());
                if (CollUtil.isNotEmpty(addSignTasks)) { // 处理加签任务
                    approveTasks.addAll(convertList(addSignTasks, item -> BpmProcessInstanceConvert.INSTANCE.buildApprovalTaskInfo(item)));
                }
                return approvalNodeInfo.setTasks(approveTasks);
            }

            // 结束节点
            if (END_NODE.getBpmnType().equals(activity.getActivityType())) {
                return approvalNodeInfo.setNodeType(END_NODE.getType()).setStatus(processInstanceStatus);
            }

            throw new IllegalArgumentException("未知类型：" + activity);
        });
        if (CollUtil.isEmpty(approvalNodes)) {
            return approvalNodes;
        }

        // 特殊：BPMN 的 startEvent 转换：approvalNodes 有节点，说明已经发起，需要给 BPMN 添加一个发起人
        // TODO 芋艿：这里，需要根据 bpmn 进行判断
        ApprovalNodeInfo startNode = CollUtil.getFirst(approvalNodes);
        if (ObjectUtil.notEqual(BpmSimpleModelNodeType.START_USER_NODE.getType(), startNode.getNodeType())) {
            ApprovalTaskInfo startTask = new ApprovalTaskInfo().setId(BpmnModelConstants.START_USER_NODE_ID)
                    .setAssignee(startUserId).setStatus(BpmTaskStatusEnum.APPROVE.getStatus());
            startNode = new ApprovalNodeInfo().setId(startTask.getId())
                    .setName(BpmSimpleModelNodeType.START_USER_NODE.getName()).setNodeType(START_USER_NODE.getType())
                    .setStatus(startTask.getStatus()).setTasks(ListUtil.of(startTask));
            approvalNodes.add(0, startNode);
        }
        return approvalNodes;
    }

    private List<ApprovalNodeInfo> getRunApproveNodeList(List<HistoricActivityInstance> activities,
                                                         List<HistoricTaskInstance> tasks,
                                                         BpmnModel bpmnModel,
                                                         Long startUserId,
                                                         ProcessInstance processInstance) {
        // 构建运行中的任务，基于 activityId 分组
        List<HistoricActivityInstance> runActivities = filterList(activities, activity -> activity.getEndTime() == null
                && (StrUtil.equalsAny(activity.getActivityType(), ELEMENT_TASK_USER)));
        Map<String, List<HistoricActivityInstance>> runningTaskMap = convertMultiMap(runActivities, HistoricActivityInstance::getActivityId);

        // TODO @芋艿：待简化
        Map<String, HistoricTaskInstance> taskMap = convertMap(tasks, HistoricTaskInstance::getId);
        Map<String, List<HistoricTaskInstance>> addSignTaskMap = convertMultiMap(
                filterList(tasks, task -> StrUtil.isNotEmpty(task.getParentTaskId())), HistoricTaskInstance::getParentTaskId);

        // 按照 activityId 分组，构建 ApprovalNodeInfo 节点
        return convertList(runningTaskMap.entrySet(), entry -> {
            String activityId = entry.getKey();
            List<HistoricActivityInstance> xxxactivities = entry.getValue();
            ApprovalNodeInfo approvalNodeInfo = new ApprovalNodeInfo();
            approvalNodeInfo.setNodeType(APPROVE_NODE.getType());
            approvalNodeInfo.setStatus(RUNNING.getStatus());
            List<ApprovalTaskInfo> approveTasks = CollUtil.newArrayList();
            int i = 0; // TODO @jason：直接获取第一个，这样逻辑会更简单纯粹一点，firActivity；这样，循环里面，就不用做这个事情了哈。
            for (HistoricActivityInstance activity : xxxactivities) {
                HistoricTaskInstance task = taskMap.get(activity.getTaskId());
                // 取第一个任务， 会签/或签的任务。开始时间相同的
                if (i == 0) {
                    approvalNodeInfo.setId(activity.getId()).setName(activity.getActivityName()).
                            setStartTime(DateUtils.of(activity.getStartTime()));
                }
                // tasks
                ApprovalTaskInfo approveTask = BpmProcessInstanceConvert.INSTANCE.buildApprovalTaskInfo(task);
                approveTasks.add(approveTask);
                List<HistoricTaskInstance> addSignTasks = addSignTaskMap.get(activity.getTaskId());
                if (CollUtil.isNotEmpty(addSignTasks)) { // 处理加签任务
                    approveTasks.addAll(convertList(addSignTasks, item -> BpmProcessInstanceConvert.INSTANCE.buildApprovalTaskInfo(item)));
                }
                i++;
            }
            approvalNodeInfo.setTasks(approveTasks);

            // TODO 芋艿：这里的预测说明：
            FlowElement flowNode = BpmnModelUtils.getFlowElementById(bpmnModel, activityId);
            if (BpmnModelUtils.isSequentialUserTask(flowNode)) {
                Integer candidateStrategy = BpmnModelUtils.parseCandidateStrategy(flowNode);
                String candidateParam = BpmnModelUtils.parseCandidateParam(flowNode);
                List<UserSimpleBaseVO> candidateUserList = getNotRunTaskCandidateUserList(
                        startUserId, processInstance, flowNode.getId(), candidateStrategy, candidateParam);
                ApprovalTaskInfo approvalTaskInfo = CollUtil.getFirst(approvalNodeInfo.getTasks());
                Assert.notNull(approvalTaskInfo, "任务不能为空"); // TODO 芋艿：提示改下
                // 找到当前审批人在候选人列表的位置
                int index = CollUtil.indexOf(candidateUserList, user -> user.getId().equals(approvalTaskInfo.getAssignee()));
                // 截取当前审批人位置后面的候选人, 不包含当前审批人
                approvalNodeInfo.setCandidateUsers(CollUtil.sub(candidateUserList, index + 1, candidateUserList.size()));
            }
            return approvalNodeInfo;
        });
    }

    private List<ApprovalNodeInfo> getSimulateApproveNodeList(BpmProcessDefinitionInfoDO processDefinitionInfo,
                                                              ProcessInstance processInstance,
                                                              BpmnModel bpmnModel,
                                                              Long startUserId,
                                                              Map<String, Object> processVariable,
                                                              List<HistoricActivityInstance> historicActivityList) {
        Set<String> runNodeIds = convertSet(historicActivityList, HistoricActivityInstance::getActivityId);
        // 情况一：BPMN 设计器
        if (Objects.equals(BpmModelTypeEnum.BPMN.getType(), processDefinitionInfo.getModelType())) {
            List<FlowElement> flowElements = BpmnModelUtils.simulateProcess(bpmnModel, processVariable);
            return convertList(flowElements, flowElement -> buildNotRunApproveNode(startUserId, processInstance, flowElement, runNodeIds));
        // 情况二：SIMPLE 设计器
        }
        if (Objects.equals(BpmModelTypeEnum.SIMPLE.getType(), processDefinitionInfo.getModelType())) {
            BpmSimpleModelNodeVO simpleModel = JsonUtils.parseObject(processDefinitionInfo.getSimpleModel(), BpmSimpleModelNodeVO.class);
            List<BpmSimpleModelNodeVO> simpleNodes = SimpleModelUtils.simulateProcess(simpleModel, processVariable);
            return convertList(simpleNodes, simpleNode -> buildNotRunApproveNodes(startUserId, processInstance, simpleNode, runNodeIds));
        }
        throw new IllegalArgumentException(""); // TODO 芋艿：优化下
    }

    private ApprovalNodeInfo buildNotRunApproveNodes(Long startUserId,
                                                     ProcessInstance processInstance,
                                                     BpmSimpleModelNodeVO node,
                                                     Set<String> runNodeIds) {
        if (runNodeIds.contains(node.getId())) {
            return null;
        }
        ApprovalNodeInfo approvalNodeInfo = new ApprovalNodeInfo().setNodeType(node.getType())
                .setName(node.getName()).setStatus(NOT_START.getStatus());
        // 1. 对需要人工审批的审批节点，进行预测
        if (APPROVE_NODE.getType().equals(node.getType())
                || START_USER_NODE.getType().equals(node.getType())) {

            Integer candidateStrategy = START_USER_NODE.getType().equals(node.getType()) ?
                    START_USER.getStrategy() : node.getCandidateStrategy();
            approvalNodeInfo.setCandidateUsers(
                    getNotRunTaskCandidateUserList(startUserId, processInstance, node.getId(), candidateStrategy, node.getCandidateParam()));
            // TODO 芋艿：需要测试非 USER 审批的情况；
            return approvalNodeInfo;
            // 2. 结束节点
        }
        if (END_NODE.getType().equals(node.getType())) {
            return approvalNodeInfo;
        }
        // TODO 芋艿：抄送节点
        return null;
    }

    private ApprovalNodeInfo buildNotRunApproveNode(Long startUserId,
                                                    ProcessInstance processInstance,
                                                    FlowElement node,
                                                    Set<String> runNodeIds) {
        if (runNodeIds.contains(node.getId())) {
            return null;
        }
        // 1. 对需要人工审批的审批节点，进行预测
        if (node instanceof UserTask) {
            ApprovalNodeInfo approvalNodeInfo = new ApprovalNodeInfo().setNodeType(APPROVE_NODE.getType())
                    .setName(node.getName()).setStatus(NOT_START.getStatus());
            Integer candidateStrategy = BpmnModelUtils.parseCandidateStrategy(node);
            String candidateParam = BpmnModelUtils.parseCandidateParam(node);
            approvalNodeInfo.setCandidateUsers(
                    getNotRunTaskCandidateUserList(startUserId, processInstance, node.getId(), candidateStrategy, candidateParam));
            return approvalNodeInfo;
            // 2. 结束节点
        }
        if (node instanceof EndEvent) {
            return new ApprovalNodeInfo().setNodeType(END_NODE.getType())
                    .setName(node.getName()).setStatus(NOT_START.getStatus());
        }
        return null;
    }

    private List<UserSimpleBaseVO> getNotRunTaskCandidateUserList(Long startUserId, ProcessInstance processInstance, String activityId,
                                                                  Integer candidateStrategy, String candidateParam) {
        BpmTaskCandidateStrategy taskCandidateStrategy = bpmTaskCandidateInvoker.getCandidateStrategy(candidateStrategy);
        Set<Long> userIds = taskCandidateStrategy.calculateUsers(startUserId, processInstance, activityId, candidateParam);
        Map<Long, AdminUserRespDTO> adminUserMap = adminUserApi.getUserMap(userIds);
        // 需要按照候选人的顺序返回。原因是，依次审批需要按顺序展示用户
        return convertList(userIds, userId -> BeanUtils.toBean(adminUserMap.get(userId), UserSimpleBaseVO.class));
    }

    @Override
    public BpmProcessInstanceBpmnModelViewRespVO getProcessInstanceBpmnModelView(String id) {
        // 1.1 获得流程实例
        HistoricProcessInstance processInstance = getHistoricProcessInstance(id);
        if (processInstance == null) {
            return null;
        }
        // 1.2 获得流程定义
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processInstance.getProcessDefinitionId());
        if (bpmnModel == null) {
            return null;
        }
        // 1.3 获得流程实例对应的活动实例列表 + 任务列表
        List<HistoricActivityInstance> activityInstances = getActivityListByProcessInstanceId(id);
        List<HistoricTaskInstance> taskInstances = taskService.getTaskListByProcessInstanceId(id, true);

        // 2.1 拼接进度信息
        Set<String> unfinishedTaskActivityIds = convertSet(activityInstances, HistoricActivityInstance::getActivityId,
                activityInstance -> activityInstance.getEndTime() == null);
        Set<String> finishedTaskActivityIds = convertSet(activityInstances, HistoricActivityInstance::getActivityId,
                activityInstance -> activityInstance.getEndTime() != null
                        && ObjectUtil.notEqual(activityInstance.getActivityType(), BpmnXMLConstants.ELEMENT_SEQUENCE_FLOW));
        Set<String> finishedSequenceFlowActivityIds = convertSet(activityInstances, HistoricActivityInstance::getActivityId,
                activityInstance -> activityInstance.getEndTime() != null
                        && ObjectUtil.equals(activityInstance.getActivityType(), BpmnXMLConstants.ELEMENT_SEQUENCE_FLOW));
        // 特殊：会签情况下，会有部分已完成（审批）、部分未完成（待审批），此时需要 finishedTaskActivityIds 移除掉
        unfinishedTaskActivityIds.removeAll(finishedTaskActivityIds);
        // 特殊：如果流程实例被拒绝，则需要计算是哪个活动节点。
        // 注意，只取最后一个。因为会存在多次拒绝的情况，拒绝驳回到指定节点
        Set<String> rejectTaskActivityIds = CollUtil.newHashSet();
        if (BpmProcessInstanceStatusEnum.isRejectStatus(FlowableUtils.getProcessInstanceStatus(processInstance))) {
            taskInstances.stream()
                    .filter(task -> BpmTaskStatusEnum.isRejectStatus(FlowableUtils.getTaskStatus(task)))
                    .max(Comparator.comparing(HistoricTaskInstance::getEndTime))
                    .ifPresent(reject -> rejectTaskActivityIds.add(reject.getTaskDefinitionKey()));
            finishedTaskActivityIds.removeAll(rejectTaskActivityIds);
        }

        // 2.2 拼接基础信息
        Set<Long> userIds = SetUtils.asSet(Long.valueOf(processInstance.getStartUserId()));
        taskInstances.forEach(task -> {
            CollUtil.addIfAbsent(userIds, NumberUtils.parseLong((task.getAssignee())));
            CollUtil.addIfAbsent(userIds, NumberUtils.parseLong((task.getOwner())));
        });
        Map<Long, AdminUserRespDTO> userMap = adminUserApi.getUserMap(userIds);
        Map<Long, DeptRespDTO> deptMap = deptApi.getDeptMap(
                convertSet(userMap.values(), AdminUserRespDTO::getDeptId));
        return INSTANCE.buildProcessInstanceBpmnModelView(processInstance, taskInstances, bpmnModel,
                unfinishedTaskActivityIds, finishedTaskActivityIds, finishedSequenceFlowActivityIds, rejectTaskActivityIds,
                userMap, deptMap);
    }

    private List<HistoricActivityInstance> getActivityListByProcessInstanceId(String id) {
        return historyService.createHistoricActivityInstanceQuery().processInstanceId(id)
                .orderByHistoricActivityInstanceStartTime().asc().list();
    }

    // ========== Update 写入相关方法 ==========

    @Override
    @Transactional(rollbackFor = Exception.class)
    public String createProcessInstance(Long userId, @Valid BpmProcessInstanceCreateReqVO createReqVO) {
        // 获得流程定义
        ProcessDefinition definition = processDefinitionService.getProcessDefinition(createReqVO.getProcessDefinitionId());
        // 发起流程
        return createProcessInstance0(userId, definition, createReqVO.getVariables(), null,
                createReqVO.getStartUserSelectAssignees());
    }

    @Override
    public String createProcessInstance(Long userId, @Valid BpmProcessInstanceCreateReqDTO createReqDTO) {
        // 获得流程定义
        ProcessDefinition definition = processDefinitionService.getActiveProcessDefinition(createReqDTO.getProcessDefinitionKey());
        // 发起流程
        return createProcessInstance0(userId, definition, createReqDTO.getVariables(), createReqDTO.getBusinessKey(),
                createReqDTO.getStartUserSelectAssignees());
    }

    private String createProcessInstance0(Long userId, ProcessDefinition definition,
                                          Map<String, Object> variables, String businessKey,
                                          Map<String, List<Long>> startUserSelectAssignees) {
        // 1.1 校验流程定义
        if (definition == null) {
            throw exception(PROCESS_DEFINITION_NOT_EXISTS);
        }
        if (definition.isSuspended()) {
            throw exception(PROCESS_DEFINITION_IS_SUSPENDED);
        }
        BpmProcessDefinitionInfoDO processDefinitionInfo = processDefinitionService.getProcessDefinitionInfo(definition.getId());
        if (processDefinitionInfo == null) {
            throw exception(PROCESS_DEFINITION_NOT_EXISTS);
        }
        // 1.2 校验是否能够发起
        if (!processDefinitionService.canUserStartProcessDefinition(processDefinitionInfo, userId)) {
            throw exception(PROCESS_INSTANCE_START_USER_CAN_START);
        }
        // 1.3 校验发起人自选审批人
        validateStartUserSelectAssignees(definition, startUserSelectAssignees);

        // 2. 创建流程实例
        if (variables == null) {
            variables = new HashMap<>();
        }
        FlowableUtils.filterProcessInstanceFormVariable(variables); // 过滤一下，避免 ProcessInstance 系统级的变量被占用
        variables.put(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS, // 流程实例状态：审批中
                BpmProcessInstanceStatusEnum.RUNNING.getStatus());
        if (CollUtil.isNotEmpty(startUserSelectAssignees)) {
            variables.put(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_START_USER_SELECT_ASSIGNEES, startUserSelectAssignees);
        }
        ProcessInstance instance = runtimeService.createProcessInstanceBuilder()
                .processDefinitionId(definition.getId())
                .businessKey(businessKey)
                .name(definition.getName().trim())
                .variables(variables)
                .start();
        return instance.getId();
    }

    private void validateStartUserSelectAssignees(ProcessDefinition definition, Map<String, List<Long>> startUserSelectAssignees) {
        // 1. 获得发起人自选审批人的 UserTask 列表
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(definition.getId());
        List<UserTask> userTaskList = BpmTaskCandidateStartUserSelectStrategy.getStartUserSelectUserTaskList(bpmnModel);
        if (CollUtil.isEmpty(userTaskList)) {
            return;
        }

        // 2. 校验发起人自选审批人的 UserTask 是否都配置了
        userTaskList.forEach(userTask -> {
            List<Long> assignees = startUserSelectAssignees != null ? startUserSelectAssignees.get(userTask.getId()) : null;
            if (CollUtil.isEmpty(assignees)) {
                throw exception(PROCESS_INSTANCE_START_USER_SELECT_ASSIGNEES_NOT_CONFIG, userTask.getName());
            }
            Map<Long, AdminUserRespDTO> userMap = adminUserApi.getUserMap(assignees);
            assignees.forEach(assignee -> {
                if (userMap.get(assignee) == null) {
                    throw exception(PROCESS_INSTANCE_START_USER_SELECT_ASSIGNEES_NOT_EXISTS, userTask.getName(), assignee);
                }
            });
        });
    }

    @Override
    public void cancelProcessInstanceByStartUser(Long userId, @Valid BpmProcessInstanceCancelReqVO cancelReqVO) {
        // 1.1 校验流程实例存在
        ProcessInstance instance = getProcessInstance(cancelReqVO.getId());
        if (instance == null) {
            throw exception(PROCESS_INSTANCE_CANCEL_FAIL_NOT_EXISTS);
        }
        // 1.2 只能取消自己的
        if (!Objects.equals(instance.getStartUserId(), String.valueOf(userId))) {
            throw exception(PROCESS_INSTANCE_CANCEL_FAIL_NOT_SELF);
        }

        // 2. 取消流程
        updateProcessInstanceCancel(cancelReqVO.getId(),
                BpmReasonEnum.CANCEL_PROCESS_INSTANCE_BY_START_USER.format(cancelReqVO.getReason()));
    }

    @Override
    public void cancelProcessInstanceByAdmin(Long userId, BpmProcessInstanceCancelReqVO cancelReqVO) {
        // 1.1 校验流程实例存在
        ProcessInstance instance = getProcessInstance(cancelReqVO.getId());
        if (instance == null) {
            throw exception(PROCESS_INSTANCE_CANCEL_FAIL_NOT_EXISTS);
        }

        // 2. 取消流程
        AdminUserRespDTO user = adminUserApi.getUser(userId);
        updateProcessInstanceCancel(cancelReqVO.getId(),
                BpmReasonEnum.CANCEL_PROCESS_INSTANCE_BY_ADMIN.format(user.getNickname(), cancelReqVO.getReason()));
    }

    private void updateProcessInstanceCancel(String id, String reason) {
        // 1. 更新流程实例 status
        runtimeService.setVariable(id, BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.CANCEL.getStatus());
        runtimeService.setVariable(id, BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_REASON, reason);

        // 2. 结束流程
        taskService.moveTaskToEnd(id);
    }

    @Override
    public void updateProcessInstanceReject(ProcessInstance processInstance, String reason) {
        runtimeService.setVariable(processInstance.getProcessInstanceId(), BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.REJECT.getStatus());
        runtimeService.setVariable(processInstance.getProcessInstanceId(), BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_REASON,
                BpmReasonEnum.REJECT_TASK.format(reason));
    }

    // ========== Event 事件相关方法 ==========

    @Override
    public void processProcessInstanceCompleted(ProcessInstance instance) {
        // 注意：需要基于 instance 设置租户编号，避免 Flowable 内部异步时，丢失租户编号
        FlowableUtils.execute(instance.getTenantId(), () -> {
            // 1.1 获取当前状态
            Integer status = (Integer) instance.getProcessVariables().get(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS);
            String reason = (String) instance.getProcessVariables().get(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_REASON);
            // 1.2 当流程状态还是审批状态中，说明审批通过了，则变更下它的状态
            // 为什么这么处理？因为流程完成，并且完成了，说明审批通过了
            if (Objects.equals(status, BpmProcessInstanceStatusEnum.RUNNING.getStatus())) {
                status = BpmProcessInstanceStatusEnum.APPROVE.getStatus();
                runtimeService.setVariable(instance.getId(), BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS, status);
            }

            // 2. 发送对应的消息通知
            if (Objects.equals(status, BpmProcessInstanceStatusEnum.APPROVE.getStatus())) {
                messageService.sendMessageWhenProcessInstanceApprove(INSTANCE.buildProcessInstanceApproveMessage(instance));
            } else if (Objects.equals(status, BpmProcessInstanceStatusEnum.REJECT.getStatus())) {
                messageService.sendMessageWhenProcessInstanceReject(
                        INSTANCE.buildProcessInstanceRejectMessage(instance, reason));
            }

            // 3. 发送流程实例的状态事件
            processInstanceEventPublisher.sendProcessInstanceResultEvent(
                    INSTANCE.buildProcessInstanceStatusEvent(this, instance, status));
        });
    }

}
 \ No newline at end of file
+package cn.iocoder.yudao.module.bpm.service.task;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.collection.ListUtil;
import cn.hutool.core.lang.Assert;
import cn.hutool.core.util.ArrayUtil;
import cn.hutool.core.util.ObjectUtil;
import cn.hutool.core.util.StrUtil;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.common.util.collection.CollectionUtils;
import cn.iocoder.yudao.framework.common.util.collection.SetUtils;
import cn.iocoder.yudao.framework.common.util.date.DateUtils;
import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
import cn.iocoder.yudao.framework.common.util.number.NumberUtils;
import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
import cn.iocoder.yudao.framework.common.util.object.PageUtils;
import cn.iocoder.yudao.module.bpm.api.task.dto.BpmProcessInstanceCreateReqDTO;
import cn.iocoder.yudao.module.bpm.controller.admin.base.user.UserSimpleBaseVO;
import cn.iocoder.yudao.module.bpm.controller.admin.definition.vo.model.simple.BpmSimpleModelNodeVO;
import cn.iocoder.yudao.module.bpm.controller.admin.definition.vo.process.BpmProcessDefinitionRespVO;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.*;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmApprovalDetailRespVO.ApprovalTaskInfo;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.task.BpmTaskRespVO;
import cn.iocoder.yudao.module.bpm.convert.definition.BpmProcessDefinitionConvert;
import cn.iocoder.yudao.module.bpm.convert.task.BpmProcessInstanceConvert;
import cn.iocoder.yudao.module.bpm.dal.dataobject.definition.BpmProcessDefinitionInfoDO;
import cn.iocoder.yudao.module.bpm.enums.ErrorCodeConstants;
import cn.iocoder.yudao.module.bpm.enums.definition.BpmModelTypeEnum;
import cn.iocoder.yudao.module.bpm.enums.definition.BpmSimpleModelNodeType;
import cn.iocoder.yudao.module.bpm.enums.task.BpmProcessInstanceStatusEnum;
import cn.iocoder.yudao.module.bpm.enums.task.BpmReasonEnum;
import cn.iocoder.yudao.module.bpm.enums.task.BpmTaskStatusEnum;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.BpmTaskCandidateInvoker;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.BpmTaskCandidateStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.strategy.BpmTaskCandidateStartUserSelectStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnVariableConstants;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.event.BpmProcessInstanceEventPublisher;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.BpmnModelUtils;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.FlowableUtils;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.util.SimpleModelUtils;
import cn.iocoder.yudao.module.bpm.service.definition.BpmProcessDefinitionService;
import cn.iocoder.yudao.module.bpm.service.message.BpmMessageService;
import cn.iocoder.yudao.module.system.api.dept.DeptApi;
import cn.iocoder.yudao.module.system.api.dept.dto.DeptRespDTO;
import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
import cn.iocoder.yudao.module.system.api.user.dto.AdminUserRespDTO;
import jakarta.annotation.Resource;
import jakarta.validation.Valid;
import lombok.extern.slf4j.Slf4j;
import org.flowable.bpmn.constants.BpmnXMLConstants;
import org.flowable.bpmn.model.BpmnModel;
import org.flowable.bpmn.model.EndEvent;
import org.flowable.bpmn.model.FlowElement;
import org.flowable.bpmn.model.UserTask;
import org.flowable.engine.HistoryService;
import org.flowable.engine.RuntimeService;
import org.flowable.engine.history.HistoricActivityInstance;
import org.flowable.engine.history.HistoricProcessInstance;
import org.flowable.engine.history.HistoricProcessInstanceQuery;
import org.flowable.engine.repository.ProcessDefinition;
import org.flowable.engine.runtime.ProcessInstance;
import org.flowable.task.api.history.HistoricTaskInstance;
import org.springframework.context.annotation.Lazy;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.validation.annotation.Validated;

import java.util.*;

import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.*;
import static cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmApprovalDetailRespVO.NodeInfo;
import static cn.iocoder.yudao.module.bpm.convert.task.BpmProcessInstanceConvert.INSTANCE;
import static cn.iocoder.yudao.module.bpm.enums.ErrorCodeConstants.*;
import static cn.iocoder.yudao.module.bpm.enums.definition.BpmSimpleModelNodeType.*;
import static cn.iocoder.yudao.module.bpm.enums.task.BpmTaskStatusEnum.NOT_START;
import static cn.iocoder.yudao.module.bpm.enums.task.BpmTaskStatusEnum.RUNNING;
import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmTaskCandidateStrategyEnum.START_USER;
import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants.START_USER_NODE_ID;
import static java.util.Arrays.asList;
import static java.util.Collections.singletonList;
import static org.flowable.bpmn.constants.BpmnXMLConstants.*;

/**
 * 流程实例 Service 实现类
 * <p>
 * ProcessDefinition & ProcessInstance & Execution & Task 的关系：
 * 1. <a href="https://blog.csdn.net/bobozai86/article/details/105210414" />
 * <p>
 * HistoricProcessInstance & ProcessInstance 的关系：
 * 1. <a href=" https://my.oschina.net/843294669/blog/71902" />
 * <p>
 * 简单来说，前者 = 历史 + 运行中的流程实例，后者仅是运行中的流程实例
 *
 * @author 芋道源码
 */
@Service
@Validated
@Slf4j
public class BpmProcessInstanceServiceImpl implements BpmProcessInstanceService {

    @Resource
    private RuntimeService runtimeService;
    @Resource
    private HistoryService historyService;

    @Resource
    private BpmProcessDefinitionService processDefinitionService;
    @Resource
    @Lazy // 避免循环依赖
    private BpmTaskService taskService;
    @Resource
    private BpmMessageService messageService;
    @Resource
    private BpmTaskCandidateInvoker bpmTaskCandidateInvoker;

    @Resource
    private AdminUserApi adminUserApi;
    @Resource
    private DeptApi deptApi;

    @Resource
    private BpmProcessInstanceEventPublisher processInstanceEventPublisher;

    // ========== Query 查询相关方法 ==========

    @Override
    public ProcessInstance getProcessInstance(String id) {
        return runtimeService.createProcessInstanceQuery()
                .includeProcessVariables()
                .processInstanceId(id)
                .singleResult();
    }

    @Override
    public List<ProcessInstance> getProcessInstances(Set<String> ids) {
        return runtimeService.createProcessInstanceQuery().processInstanceIds(ids).list();
    }

    @Override
    public HistoricProcessInstance getHistoricProcessInstance(String id) {
        return historyService.createHistoricProcessInstanceQuery().processInstanceId(id).includeProcessVariables().singleResult();
    }

    @Override
    public List<HistoricProcessInstance> getHistoricProcessInstances(Set<String> ids) {
        return historyService.createHistoricProcessInstanceQuery().processInstanceIds(ids).list();
    }

    @Override
    public PageResult<HistoricProcessInstance> getProcessInstancePage(Long userId,
                                                                      BpmProcessInstancePageReqVO pageReqVO) {
        // 通过 BpmProcessInstanceExtDO 表，先查询到对应的分页
        HistoricProcessInstanceQuery processInstanceQuery = historyService.createHistoricProcessInstanceQuery()
                .includeProcessVariables()
                .processInstanceTenantId(FlowableUtils.getTenantId())
                .orderByProcessInstanceStartTime().desc();
        if (userId != null) { // 【我的流程】菜单时，需要传递该字段
            processInstanceQuery.startedBy(String.valueOf(userId));
        } else if (pageReqVO.getStartUserId() != null) { // 【管理流程】菜单时，才会传递该字段
            processInstanceQuery.startedBy(String.valueOf(pageReqVO.getStartUserId()));
        }
        if (StrUtil.isNotEmpty(pageReqVO.getName())) {
            processInstanceQuery.processInstanceNameLike("%" + pageReqVO.getName() + "%");
        }
        if (StrUtil.isNotEmpty(pageReqVO.getProcessDefinitionKey())) {
            processInstanceQuery.processDefinitionKey(pageReqVO.getProcessDefinitionKey());
        }
        if (StrUtil.isNotEmpty(pageReqVO.getCategory())) {
            processInstanceQuery.processDefinitionCategory(pageReqVO.getCategory());
        }
        if (pageReqVO.getStatus() != null) {
            processInstanceQuery.variableValueEquals(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS, pageReqVO.getStatus());
        }
        if (ArrayUtil.isNotEmpty(pageReqVO.getCreateTime())) {
            processInstanceQuery.startedAfter(DateUtils.of(pageReqVO.getCreateTime()[0]));
            processInstanceQuery.startedBefore(DateUtils.of(pageReqVO.getCreateTime()[1]));
        }
        // 查询数量
        long processInstanceCount = processInstanceQuery.count();
        if (processInstanceCount == 0) {
            return PageResult.empty(processInstanceCount);
        }
        // 查询列表
        List<HistoricProcessInstance> processInstanceList = processInstanceQuery.listPage(PageUtils.getStart(pageReqVO), pageReqVO.getPageSize());
        return new PageResult<>(processInstanceList, processInstanceCount);
    }


    private Map<String, String> getFormFieldsPermission(BpmnModel bpmnModel,
                                                        String activityId, String taskId) {
        // 1. 获取流程活动编号。流程活动 Id 为空事，从流程任务中获取流程活动 Id
        if (StrUtil.isEmpty(activityId) && StrUtil.isNotEmpty(taskId)) {
            activityId = Optional.ofNullable(taskService.getHistoricTask(taskId))
                    .map(HistoricTaskInstance::getTaskDefinitionKey).orElse(null);
        }
        if (StrUtil.isEmpty(activityId)) {
            return null;
        }

        // 2. 从 BpmnModel 中解析表单字段权限
        return BpmnModelUtils.parseFormFieldsPermission(bpmnModel, activityId);
    }

    @Override
    public BpmApprovalDetailRespVO getApprovalDetail(Long loginUserId, BpmApprovalDetailReqVO reqVO) {
        // 1.1 从 reqVO 中，读取公共变量
        Long startUserId = loginUserId; // 流程发起人
        HistoricProcessInstance historicProcessInstance = null; // 流程实例
        ProcessInstance processInstance = null; // 流程
        Integer processInstanceStatus = BpmProcessInstanceStatusEnum.NOT_START.getStatus(); // 流程状态
        Map<String, Object> processVariables = reqVO.getProcessVariables(); // 流程变量
        // 1.2 如果是流程已发起的场景，则使用流程实例的数据
        if (reqVO.getProcessInstanceId() != null) {
            historicProcessInstance = getHistoricProcessInstance(reqVO.getProcessInstanceId());
            if (historicProcessInstance == null) {
                throw exception(ErrorCodeConstants.PROCESS_INSTANCE_NOT_EXISTS);
            }
            processInstance = getProcessInstance(historicProcessInstance.getId());
            startUserId = Long.valueOf(historicProcessInstance.getStartUserId());
            processInstanceStatus = FlowableUtils.getProcessInstanceStatus(historicProcessInstance);
            processVariables = historicProcessInstance.getProcessVariables();
        }
        // 1.3 读取其它相关数据
        ProcessDefinition processDefinition = processDefinitionService.getProcessDefinition(
                historicProcessInstance != null ? historicProcessInstance.getProcessDefinitionId() : reqVO.getProcessDefinitionId());
        BpmProcessDefinitionInfoDO processDefinitionInfo = processDefinitionService.getProcessDefinitionInfo(processDefinition.getId());
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processDefinition.getId());

        // 2.1 已结束 + 进行中的流程节点
        List<NodeInfo> endApprovalNodeInfos = null; // 已结束的审批信息
        List<NodeInfo> runApprovalNodeInfos = null; // 进行中的审批信息
        List<HistoricActivityInstance> activities = null; // 流程实例列表
        if (reqVO.getProcessInstanceId() != null) {
            activities = taskService.getActivityListByProcessInstanceId(reqVO.getProcessInstanceId());
            List<HistoricTaskInstance> tasks = taskService.getTaskListByProcessInstanceId(reqVO.getProcessInstanceId(), true);
            endApprovalNodeInfos = getEndApprovalNodeInfoList(startUserId, processDefinitionInfo, processInstanceStatus, activities, tasks);
            runApprovalNodeInfos = getRunApproveNodeList(startUserId, bpmnModel, processInstance, activities, tasks);
        }

        // 2.2 流程已经结束，直接 return，无需预测
        if (BpmProcessInstanceStatusEnum.isProcessEndStatus(processInstanceStatus)) {
            return buildApprovalDetail(reqVO, bpmnModel, processDefinition, processDefinitionInfo, historicProcessInstance, processInstanceStatus,
                    endApprovalNodeInfos, runApprovalNodeInfos, null, null);
        }

        // 3.1 计算当前登录用户的待办任务
        // TODO @jason：有一个极端情况，如果一个用户有 2 个 task A 和 B，A 已经通过，B 需要审核。这个时，通过 A 进来，todo 拿到 B，会不会表单权限不一致哈。
        // 目前的想法，是不是不依赖前端传递参数。而是后端推导，按照一个顺序。待审批 》 taskId/activityId
        BpmTaskRespVO todoTask = taskService.getFirstTodoTask(loginUserId, reqVO.getProcessInstanceId());

        // 3.2 预测未运行节点的审批信息
        List<NodeInfo> simulateApprovalNodeInfos = getSimulateApproveNodeList(processDefinitionInfo, processInstance, bpmnModel, startUserId, processVariables,
                activities);
        return buildApprovalDetail(reqVO, bpmnModel, processDefinition, processDefinitionInfo, historicProcessInstance, processInstanceStatus,
                endApprovalNodeInfos, runApprovalNodeInfos, simulateApprovalNodeInfos, todoTask);
    }

    private BpmApprovalDetailRespVO buildApprovalDetail(BpmApprovalDetailReqVO reqVO,
                                                        BpmnModel bpmnModel,
                                                        ProcessDefinition processDefinition,
                                                        BpmProcessDefinitionInfoDO processDefinitionInfo,
                                                        HistoricProcessInstance processInstance,
                                                        Integer processInstanceStatus,
                                                        List<NodeInfo> endApprovalNodeInfos,
                                                        List<NodeInfo> runningApprovalNodeInfos,
                                                        List<NodeInfo> simulateApprovalNodeInfos,
                                                        BpmTaskRespVO todoTask) {
        BpmProcessInstanceRespVO processInstanceResp = null;
        if (processInstance != null) {
            AdminUserRespDTO startUser = adminUserApi.getUser(NumberUtils.parseLong(processInstance.getStartUserId()));
            DeptRespDTO dept = null;
            if (startUser != null && startUser.getDeptId() != null) {
                dept = deptApi.getDept(startUser.getDeptId());
            }
            processInstanceResp = INSTANCE.buildProcessInstance(processInstance, null,
                    null, startUser, dept);
        }
        List<UserTask> userTaskList = BpmTaskCandidateStartUserSelectStrategy.getStartUserSelectUserTaskList(bpmnModel);
        BpmProcessDefinitionRespVO definitionResp = BpmProcessDefinitionConvert.INSTANCE.buildProcessDefinition(
                processDefinition, null, processDefinitionInfo, null, null, bpmnModel, userTaskList
        );

        // 4. 表单权限
        Map<String, String> formFieldsPermission = getFormFieldsPermission(bpmnModel, reqVO.getActivityId(), reqVO.getTaskId());
        return new BpmApprovalDetailRespVO().setStatus(processInstanceStatus)
                .setProcessDefinition(definitionResp)
                .setProcessInstance(processInstanceResp)
                .setFormFieldsPermission(formFieldsPermission)
                .setTodoTask(todoTask)
                .setApproveNodes(CollectionUtils.newArrayList(asList(endApprovalNodeInfos, runningApprovalNodeInfos, simulateApprovalNodeInfos)));
    }

    private List<NodeInfo> getEndApprovalNodeInfoList(Long startUserId,
                                                      BpmProcessDefinitionInfoDO processDefinitionInfo,
                                                      Integer processInstanceStatus,
                                                      List<HistoricActivityInstance> activities,
                                                      List<HistoricTaskInstance> tasks) {
        // 遍历 tasks 列表，只处理已结束的 UserTask
        // 为什么不通过 activities 呢？因为，加签场景下，它只存在于 tasks，没有 activities，导致如果遍历 activities 的话，它无法成为一个节点
        List<HistoricTaskInstance> endTasks = filterList(tasks, task -> task.getEndTime() != null);
        List<NodeInfo> approvalNodes = convertList(endTasks, task -> {
            NodeInfo approvalNodeInfo = new NodeInfo().setId(task.getTaskDefinitionKey()).setName(task.getName())
                    .setStartTime(DateUtils.of(task.getCreateTime())).setEndTime(DateUtils.of(task.getEndTime()))
                    .setStatus(FlowableUtils.getTaskStatus(task));
            approvalNodeInfo.setNodeType(START_USER_NODE_ID.equals(approvalNodeInfo.getId()) ?
                            BpmSimpleModelNodeType.START_USER_NODE.getType() : BpmSimpleModelNodeType.APPROVE_NODE.getType());
            approvalNodeInfo.setTasks(singletonList(INSTANCE.buildApprovalTaskInfo(task)));
            return approvalNodeInfo;
        });

        // 遍历 activities，只处理已结束的 StartEvent、EndEvent
        List<HistoricActivityInstance> endActivities = filterList(activities, activity -> activity.getEndTime() != null
                && (StrUtil.equalsAny(activity.getActivityType(), ELEMENT_EVENT_START, ELEMENT_EVENT_END)));
        endActivities.forEach(activity -> {
            // StartEvent：只处理 BPMN 的场景。因为，SIMPLE 情况下，已经有 START_USER_NODE 节点
            if (ELEMENT_EVENT_START.equals(activity.getActivityType())
                    && BpmModelTypeEnum.BPMN.getType().equals(processDefinitionInfo.getModelType())) {
                ApprovalTaskInfo startTask = new ApprovalTaskInfo().setId(BpmnModelConstants.START_USER_NODE_ID)
                        .setAssignee(startUserId).setStatus(BpmTaskStatusEnum.APPROVE.getStatus());
                NodeInfo startNode = new NodeInfo().setId(startTask.getId())
                        .setName(BpmSimpleModelNodeType.START_USER_NODE.getName()).setNodeType(START_USER_NODE.getType())
                        .setStatus(startTask.getStatus()).setTasks(ListUtil.of(startTask));
                approvalNodes.add(0, startNode);
                return;
            }
            // EndEvent
            if (ELEMENT_EVENT_END.equals(activity.getActivityType())) {
                NodeInfo approvalNodeInfo = new NodeInfo().setId(activity.getId()).setName(activity.getActivityName())
                        .setNodeType(END_NODE.getType()).setStatus(processInstanceStatus)
                        .setStartTime(DateUtils.of(activity.getStartTime())).setEndTime(DateUtils.of(activity.getEndTime()));
                approvalNodes.add(approvalNodeInfo);
            }
        });
        return approvalNodes;
    }

    private List<NodeInfo> getRunApproveNodeList(Long startUserId,
                                                 BpmnModel bpmnModel,
                                                 ProcessInstance processInstance,
                                                 List<HistoricActivityInstance> activities,
                                                 List<HistoricTaskInstance> tasks) {
        // 构建运行中的任务，基于 activityId 分组
        List<HistoricActivityInstance> runActivities = filterList(activities, activity -> activity.getEndTime() == null
                && (StrUtil.equalsAny(activity.getActivityType(), ELEMENT_TASK_USER)));
        Map<String, List<HistoricActivityInstance>> runningTaskMap = convertMultiMap(runActivities, HistoricActivityInstance::getActivityId);

        // TODO @芋艿：待简化
        Map<String, HistoricTaskInstance> taskMap = convertMap(tasks, HistoricTaskInstance::getId);
        Map<String, List<HistoricTaskInstance>> addSignTaskMap = convertMultiMap(
                filterList(tasks, task -> StrUtil.isNotEmpty(task.getParentTaskId())), HistoricTaskInstance::getParentTaskId);

        // 按照 activityId 分组，构建 ApprovalNodeInfo 节点
        return convertList(runningTaskMap.entrySet(), entry -> {
            String activityId = entry.getKey();
            List<HistoricActivityInstance> xxxactivities = entry.getValue();
            NodeInfo approvalNodeInfo = new NodeInfo();
            approvalNodeInfo.setNodeType(APPROVE_NODE.getType());
            approvalNodeInfo.setStatus(RUNNING.getStatus());
            List<ApprovalTaskInfo> approveTasks = CollUtil.newArrayList();
            int i = 0; // TODO @jason：直接获取第一个，这样逻辑会更简单纯粹一点，firActivity；这样，循环里面，就不用做这个事情了哈。
            for (HistoricActivityInstance activity : xxxactivities) {
                HistoricTaskInstance task = taskMap.get(activity.getTaskId());
                // 取第一个任务， 会签/或签的任务。开始时间相同的
                if (i == 0) {
                    approvalNodeInfo.setId(activity.getId()).setName(activity.getActivityName()).
                            setStartTime(DateUtils.of(activity.getStartTime()));
                }
                // tasks
                ApprovalTaskInfo approveTask = BpmProcessInstanceConvert.INSTANCE.buildApprovalTaskInfo(task);
                approveTasks.add(approveTask);
                List<HistoricTaskInstance> addSignTasks = addSignTaskMap.get(activity.getTaskId());
                if (CollUtil.isNotEmpty(addSignTasks)) { // 处理加签任务
                    approveTasks.addAll(convertList(addSignTasks, item -> BpmProcessInstanceConvert.INSTANCE.buildApprovalTaskInfo(item)));
                }
                i++;
            }
            approvalNodeInfo.setTasks(approveTasks);

            // TODO 芋艿：这里的预测说明：
            FlowElement flowNode = BpmnModelUtils.getFlowElementById(bpmnModel, activityId);
            if (BpmnModelUtils.isSequentialUserTask(flowNode)) {
                Integer candidateStrategy = BpmnModelUtils.parseCandidateStrategy(flowNode);
                String candidateParam = BpmnModelUtils.parseCandidateParam(flowNode);
                List<UserSimpleBaseVO> candidateUserList = getNotRunTaskCandidateUserList(
                        startUserId, processInstance, flowNode.getId(), candidateStrategy, candidateParam);
                ApprovalTaskInfo approvalTaskInfo = CollUtil.getFirst(approvalNodeInfo.getTasks());
                Assert.notNull(approvalTaskInfo, "任务不能为空"); // TODO 芋艿：提示改下
                // 找到当前审批人在候选人列表的位置
                int index = CollUtil.indexOf(candidateUserList, user -> user.getId().equals(approvalTaskInfo.getAssignee()));
                // 截取当前审批人位置后面的候选人, 不包含当前审批人
                approvalNodeInfo.setCandidateUsers(CollUtil.sub(candidateUserList, index + 1, candidateUserList.size()));
            }
            return approvalNodeInfo;
        });
    }

    private List<NodeInfo> getSimulateApproveNodeList(BpmProcessDefinitionInfoDO processDefinitionInfo,
                                                      ProcessInstance processInstance,
                                                      BpmnModel bpmnModel,
                                                      Long startUserId,
                                                      Map<String, Object> processVariable,
                                                      List<HistoricActivityInstance> historicActivityList) {
        Set<String> runNodeIds = convertSet(historicActivityList, HistoricActivityInstance::getActivityId);
        // 情况一：BPMN 设计器
        if (Objects.equals(BpmModelTypeEnum.BPMN.getType(), processDefinitionInfo.getModelType())) {
            List<FlowElement> flowElements = BpmnModelUtils.simulateProcess(bpmnModel, processVariable);
            return convertList(flowElements, flowElement -> buildNotRunApproveNode(startUserId, processInstance, flowElement, runNodeIds));
        // 情况二：SIMPLE 设计器
        }
        if (Objects.equals(BpmModelTypeEnum.SIMPLE.getType(), processDefinitionInfo.getModelType())) {
            BpmSimpleModelNodeVO simpleModel = JsonUtils.parseObject(processDefinitionInfo.getSimpleModel(), BpmSimpleModelNodeVO.class);
            List<BpmSimpleModelNodeVO> simpleNodes = SimpleModelUtils.simulateProcess(simpleModel, processVariable);
            return convertList(simpleNodes, simpleNode -> buildNotRunApproveNodes(startUserId, processInstance, simpleNode, runNodeIds));
        }
        throw new IllegalArgumentException(""); // TODO 芋艿：优化下
    }

    private NodeInfo buildNotRunApproveNodes(Long startUserId,
                                             ProcessInstance processInstance,
                                             BpmSimpleModelNodeVO node,
                                             Set<String> runNodeIds) {
        if (runNodeIds.contains(node.getId())) {
            return null;
        }
        NodeInfo approvalNodeInfo = new NodeInfo().setNodeType(node.getType())
                .setName(node.getName()).setStatus(NOT_START.getStatus());
        // 1. 对需要人工审批的审批节点，进行预测
        if (APPROVE_NODE.getType().equals(node.getType())
                || START_USER_NODE.getType().equals(node.getType())) {

            Integer candidateStrategy = START_USER_NODE.getType().equals(node.getType()) ?
                    START_USER.getStrategy() : node.getCandidateStrategy();
            approvalNodeInfo.setCandidateUsers(
                    getNotRunTaskCandidateUserList(startUserId, processInstance, node.getId(), candidateStrategy, node.getCandidateParam()));
            // TODO 芋艿：需要测试非 USER 审批的情况；
            return approvalNodeInfo;
            // 2. 结束节点
        }
        if (END_NODE.getType().equals(node.getType())) {
            return approvalNodeInfo;
        }
        // TODO 芋艿：抄送节点
        return null;
    }

    private NodeInfo buildNotRunApproveNode(Long startUserId,
                                            ProcessInstance processInstance,
                                            FlowElement node,
                                            Set<String> runNodeIds) {
        if (runNodeIds.contains(node.getId())) {
            return null;
        }
        // 1. 对需要人工审批的审批节点，进行预测
        if (node instanceof UserTask) {
            NodeInfo approvalNodeInfo = new NodeInfo().setNodeType(APPROVE_NODE.getType())
                    .setName(node.getName()).setStatus(NOT_START.getStatus());
            Integer candidateStrategy = BpmnModelUtils.parseCandidateStrategy(node);
            String candidateParam = BpmnModelUtils.parseCandidateParam(node);
            approvalNodeInfo.setCandidateUsers(
                    getNotRunTaskCandidateUserList(startUserId, processInstance, node.getId(), candidateStrategy, candidateParam));
            return approvalNodeInfo;
            // 2. 结束节点
        }
        if (node instanceof EndEvent) {
            return new NodeInfo().setNodeType(END_NODE.getType())
                    .setName(node.getName()).setStatus(NOT_START.getStatus());
        }
        return null;
    }

    private List<UserSimpleBaseVO> getNotRunTaskCandidateUserList(Long startUserId, ProcessInstance processInstance, String activityId,
                                                                  Integer candidateStrategy, String candidateParam) {
        BpmTaskCandidateStrategy taskCandidateStrategy = bpmTaskCandidateInvoker.getCandidateStrategy(candidateStrategy);
        Set<Long> userIds = taskCandidateStrategy.calculateUsers(startUserId, processInstance, activityId, candidateParam);
        Map<Long, AdminUserRespDTO> adminUserMap = adminUserApi.getUserMap(userIds);
        // 需要按照候选人的顺序返回。原因是，依次审批需要按顺序展示用户
        return convertList(userIds, userId -> BeanUtils.toBean(adminUserMap.get(userId), UserSimpleBaseVO.class));
    }

    @Override
    public BpmProcessInstanceBpmnModelViewRespVO getProcessInstanceBpmnModelView(String id) {
        // 1.1 获得流程实例
        HistoricProcessInstance processInstance = getHistoricProcessInstance(id);
        if (processInstance == null) {
            return null;
        }
        // 1.2 获得流程定义
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processInstance.getProcessDefinitionId());
        if (bpmnModel == null) {
            return null;
        }
        // 1.3 获得流程实例对应的活动实例列表 + 任务列表
        List<HistoricActivityInstance> activityInstances = taskService.getActivityListByProcessInstanceId(id);
        List<HistoricTaskInstance> taskInstances = taskService.getTaskListByProcessInstanceId(id, true);

        // 2.1 拼接进度信息
        Set<String> unfinishedTaskActivityIds = convertSet(activityInstances, HistoricActivityInstance::getActivityId,
                activityInstance -> activityInstance.getEndTime() == null);
        Set<String> finishedTaskActivityIds = convertSet(activityInstances, HistoricActivityInstance::getActivityId,
                activityInstance -> activityInstance.getEndTime() != null
                        && ObjectUtil.notEqual(activityInstance.getActivityType(), BpmnXMLConstants.ELEMENT_SEQUENCE_FLOW));
        Set<String> finishedSequenceFlowActivityIds = convertSet(activityInstances, HistoricActivityInstance::getActivityId,
                activityInstance -> activityInstance.getEndTime() != null
                        && ObjectUtil.equals(activityInstance.getActivityType(), BpmnXMLConstants.ELEMENT_SEQUENCE_FLOW));
        // 特殊：会签情况下，会有部分已完成（审批）、部分未完成（待审批），此时需要 finishedTaskActivityIds 移除掉
        unfinishedTaskActivityIds.removeAll(finishedTaskActivityIds);
        // 特殊：如果流程实例被拒绝，则需要计算是哪个活动节点。
        // 注意，只取最后一个。因为会存在多次拒绝的情况，拒绝驳回到指定节点
        Set<String> rejectTaskActivityIds = CollUtil.newHashSet();
        if (BpmProcessInstanceStatusEnum.isRejectStatus(FlowableUtils.getProcessInstanceStatus(processInstance))) {
            taskInstances.stream()
                    .filter(task -> BpmTaskStatusEnum.isRejectStatus(FlowableUtils.getTaskStatus(task)))
                    .max(Comparator.comparing(HistoricTaskInstance::getEndTime))
                    .ifPresent(reject -> rejectTaskActivityIds.add(reject.getTaskDefinitionKey()));
            finishedTaskActivityIds.removeAll(rejectTaskActivityIds);
        }

        // 2.2 拼接基础信息
        Set<Long> userIds = SetUtils.asSet(Long.valueOf(processInstance.getStartUserId()));
        taskInstances.forEach(task -> {
            CollUtil.addIfAbsent(userIds, NumberUtils.parseLong((task.getAssignee())));
            CollUtil.addIfAbsent(userIds, NumberUtils.parseLong((task.getOwner())));
        });
        Map<Long, AdminUserRespDTO> userMap = adminUserApi.getUserMap(userIds);
        Map<Long, DeptRespDTO> deptMap = deptApi.getDeptMap(
                convertSet(userMap.values(), AdminUserRespDTO::getDeptId));
        return INSTANCE.buildProcessInstanceBpmnModelView(processInstance, taskInstances, bpmnModel,
                unfinishedTaskActivityIds, finishedTaskActivityIds, finishedSequenceFlowActivityIds, rejectTaskActivityIds,
                userMap, deptMap);
    }

    // ========== Update 写入相关方法 ==========

    @Override
    @Transactional(rollbackFor = Exception.class)
    public String createProcessInstance(Long userId, @Valid BpmProcessInstanceCreateReqVO createReqVO) {
        // 获得流程定义
        ProcessDefinition definition = processDefinitionService.getProcessDefinition(createReqVO.getProcessDefinitionId());
        // 发起流程
        return createProcessInstance0(userId, definition, createReqVO.getVariables(), null,
                createReqVO.getStartUserSelectAssignees());
    }

    @Override
    public String createProcessInstance(Long userId, @Valid BpmProcessInstanceCreateReqDTO createReqDTO) {
        // 获得流程定义
        ProcessDefinition definition = processDefinitionService.getActiveProcessDefinition(createReqDTO.getProcessDefinitionKey());
        // 发起流程
        return createProcessInstance0(userId, definition, createReqDTO.getVariables(), createReqDTO.getBusinessKey(),
                createReqDTO.getStartUserSelectAssignees());
    }

    private String createProcessInstance0(Long userId, ProcessDefinition definition,
                                          Map<String, Object> variables, String businessKey,
                                          Map<String, List<Long>> startUserSelectAssignees) {
        // 1.1 校验流程定义
        if (definition == null) {
            throw exception(PROCESS_DEFINITION_NOT_EXISTS);
        }
        if (definition.isSuspended()) {
            throw exception(PROCESS_DEFINITION_IS_SUSPENDED);
        }
        BpmProcessDefinitionInfoDO processDefinitionInfo = processDefinitionService.getProcessDefinitionInfo(definition.getId());
        if (processDefinitionInfo == null) {
            throw exception(PROCESS_DEFINITION_NOT_EXISTS);
        }
        // 1.2 校验是否能够发起
        if (!processDefinitionService.canUserStartProcessDefinition(processDefinitionInfo, userId)) {
            throw exception(PROCESS_INSTANCE_START_USER_CAN_START);
        }
        // 1.3 校验发起人自选审批人
        validateStartUserSelectAssignees(definition, startUserSelectAssignees);

        // 2. 创建流程实例
        if (variables == null) {
            variables = new HashMap<>();
        }
        FlowableUtils.filterProcessInstanceFormVariable(variables); // 过滤一下，避免 ProcessInstance 系统级的变量被占用
        variables.put(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS, // 流程实例状态：审批中
                BpmProcessInstanceStatusEnum.RUNNING.getStatus());
        if (CollUtil.isNotEmpty(startUserSelectAssignees)) {
            variables.put(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_START_USER_SELECT_ASSIGNEES, startUserSelectAssignees);
        }
        ProcessInstance instance = runtimeService.createProcessInstanceBuilder()
                .processDefinitionId(definition.getId())
                .businessKey(businessKey)
                .name(definition.getName().trim())
                .variables(variables)
                .start();
        return instance.getId();
    }

    private void validateStartUserSelectAssignees(ProcessDefinition definition, Map<String, List<Long>> startUserSelectAssignees) {
        // 1. 获得发起人自选审批人的 UserTask 列表
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(definition.getId());
        List<UserTask> userTaskList = BpmTaskCandidateStartUserSelectStrategy.getStartUserSelectUserTaskList(bpmnModel);
        if (CollUtil.isEmpty(userTaskList)) {
            return;
        }

        // 2. 校验发起人自选审批人的 UserTask 是否都配置了
        userTaskList.forEach(userTask -> {
            List<Long> assignees = startUserSelectAssignees != null ? startUserSelectAssignees.get(userTask.getId()) : null;
            if (CollUtil.isEmpty(assignees)) {
                throw exception(PROCESS_INSTANCE_START_USER_SELECT_ASSIGNEES_NOT_CONFIG, userTask.getName());
            }
            Map<Long, AdminUserRespDTO> userMap = adminUserApi.getUserMap(assignees);
            assignees.forEach(assignee -> {
                if (userMap.get(assignee) == null) {
                    throw exception(PROCESS_INSTANCE_START_USER_SELECT_ASSIGNEES_NOT_EXISTS, userTask.getName(), assignee);
                }
            });
        });
    }

    @Override
    public void cancelProcessInstanceByStartUser(Long userId, @Valid BpmProcessInstanceCancelReqVO cancelReqVO) {
        // 1.1 校验流程实例存在
        ProcessInstance instance = getProcessInstance(cancelReqVO.getId());
        if (instance == null) {
            throw exception(PROCESS_INSTANCE_CANCEL_FAIL_NOT_EXISTS);
        }
        // 1.2 只能取消自己的
        if (!Objects.equals(instance.getStartUserId(), String.valueOf(userId))) {
            throw exception(PROCESS_INSTANCE_CANCEL_FAIL_NOT_SELF);
        }

        // 2. 取消流程
        updateProcessInstanceCancel(cancelReqVO.getId(),
                BpmReasonEnum.CANCEL_PROCESS_INSTANCE_BY_START_USER.format(cancelReqVO.getReason()));
    }

    @Override
    public void cancelProcessInstanceByAdmin(Long userId, BpmProcessInstanceCancelReqVO cancelReqVO) {
        // 1.1 校验流程实例存在
        ProcessInstance instance = getProcessInstance(cancelReqVO.getId());
        if (instance == null) {
            throw exception(PROCESS_INSTANCE_CANCEL_FAIL_NOT_EXISTS);
        }

        // 2. 取消流程
        AdminUserRespDTO user = adminUserApi.getUser(userId);
        updateProcessInstanceCancel(cancelReqVO.getId(),
                BpmReasonEnum.CANCEL_PROCESS_INSTANCE_BY_ADMIN.format(user.getNickname(), cancelReqVO.getReason()));
    }

    private void updateProcessInstanceCancel(String id, String reason) {
        // 1. 更新流程实例 status
        runtimeService.setVariable(id, BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.CANCEL.getStatus());
        runtimeService.setVariable(id, BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_REASON, reason);

        // 2. 结束流程
        taskService.moveTaskToEnd(id);
    }

    @Override
    public void updateProcessInstanceReject(ProcessInstance processInstance, String reason) {
        runtimeService.setVariable(processInstance.getProcessInstanceId(), BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.REJECT.getStatus());
        runtimeService.setVariable(processInstance.getProcessInstanceId(), BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_REASON,
                BpmReasonEnum.REJECT_TASK.format(reason));
    }

    // ========== Event 事件相关方法 ==========

    @Override
    public void processProcessInstanceCompleted(ProcessInstance instance) {
        // 注意：需要基于 instance 设置租户编号，避免 Flowable 内部异步时，丢失租户编号
        FlowableUtils.execute(instance.getTenantId(), () -> {
            // 1.1 获取当前状态
            Integer status = (Integer) instance.getProcessVariables().get(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS);
            String reason = (String) instance.getProcessVariables().get(BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_REASON);
            // 1.2 当流程状态还是审批状态中，说明审批通过了，则变更下它的状态
            // 为什么这么处理？因为流程完成，并且完成了，说明审批通过了
            if (Objects.equals(status, BpmProcessInstanceStatusEnum.RUNNING.getStatus())) {
                status = BpmProcessInstanceStatusEnum.APPROVE.getStatus();
                runtimeService.setVariable(instance.getId(), BpmnVariableConstants.PROCESS_INSTANCE_VARIABLE_STATUS, status);
            }

            // 2. 发送对应的消息通知
            if (Objects.equals(status, BpmProcessInstanceStatusEnum.APPROVE.getStatus())) {
                messageService.sendMessageWhenProcessInstanceApprove(INSTANCE.buildProcessInstanceApproveMessage(instance));
            } else if (Objects.equals(status, BpmProcessInstanceStatusEnum.REJECT.getStatus())) {
                messageService.sendMessageWhenProcessInstanceReject(
                        INSTANCE.buildProcessInstanceRejectMessage(instance, reason));
            }

            // 3. 发送流程实例的状态事件
            processInstanceEventPublisher.sendProcessInstanceResultEvent(
                    INSTANCE.buildProcessInstanceStatusEvent(this, instance, status));
        });
    }

}
 \ No newline at end of file
@@ -6,6 +6,7 @@ import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.task.*;
 import cn.iocoder.yudao.module.bpm.enums.definition.BpmUserTaskTimeoutHandlerTypeEnum;
 import jakarta.validation.Valid;
 import org.flowable.bpmn.model.UserTask;
+import org.flowable.engine.history.HistoricActivityInstance;
 import org.flowable.task.api.Task;
 import org.flowable.task.api.history.HistoricTaskInstance;
@@ -139,12 +140,20 @@ public interface BpmTaskService {
     List<Task> getTaskListByParentTaskId(String parentTaskId);
     /**
-     * 通过任务 ID，查询任务名 Map
+     * 获得指定流程实例的活动实例列表
      *
-     * @param taskIds 任务 ID
-     * @return 任务 ID 与名字的 Map
+     * @param processInstanceId 流程实例的编号
+     * @return 活动实例列表
+     */
+    List<HistoricActivityInstance> getActivityListByProcessInstanceId(String processInstanceId);
+
+    /**
+     * 获得执行编号对应的活动实例
+     *
+     * @param executionId 执行编号
+     * @return 活动实例
      */
-    Map<String, String> getTaskNameByTaskIds(Collection<String> taskIds);
+    List<HistoricActivityInstance> getHistoricActivityListByExecutionId(String executionId);
     // ========== Update 写入相关方法 ==========
@@ -39,6 +39,7 @@ import org.flowable.engine.HistoryService;
 import org.flowable.engine.ManagementService;
 import org.flowable.engine.RuntimeService;
 import org.flowable.engine.TaskService;
+import org.flowable.engine.history.HistoricActivityInstance;
 import org.flowable.engine.history.HistoricProcessInstance;
 import org.flowable.engine.runtime.ProcessInstance;
 import org.flowable.task.api.DelegationState;
@@ -377,12 +378,14 @@ public class BpmTaskServiceImpl implements BpmTaskService {
     }
     @Override
-    public Map<String, String> getTaskNameByTaskIds(Collection<String> taskIds) {
-        if (CollUtil.isEmpty(taskIds)) {
-            return Collections.emptyMap();
-        }
-        List<Task> tasks = taskService.createTaskQuery().taskIds(taskIds).list();
-        return convertMap(tasks, Task::getId, Task::getName);
+    public List<HistoricActivityInstance> getActivityListByProcessInstanceId(String processInstanceId) {
+        return historyService.createHistoricActivityInstanceQuery().processInstanceId(processInstanceId)
+                .orderByHistoricActivityInstanceStartTime().asc().list();
+    }
+
+    @Override
+    public List<HistoricActivityInstance> getHistoricActivityListByExecutionId(String executionId) {
+        return historyService.createHistoricActivityInstanceQuery().executionId(executionId).list();
     }
     // ========== Update 写入相关方法 ==========
-package cn.iocoder.yudao.module.bpm.service.task.bo;
-
-import lombok.Data;
-
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
-import static cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmApprovalDetailRespVO.ApprovalNodeInfo;
-
-/**
- * 已经进行中的审批节点 Response BO
- *
- * @author jason
- */
-@Data
-public class AlreadyRunApproveNodeRespBO {
-
-    /**
-     * 审批节点信息数组
-     */
-    private List<ApprovalNodeInfo> approveNodes;
-
-    /**
-     * 已运行的节点 ID 数组 (对应 Bpmn XML 节点 id)
-     */
-    private Set<String> runNodeIds;
-
-    /**
-     * 正在运行的节点的审批信息（key: activityId, value: 审批信息）
-     * <p>
-     * 用于依次审批，需要加上候选人信息
-     */
-    private Map<String, ApprovalNodeInfo> runningApprovalNodes;
-
-}