【代码评审】BPM：review 快搭的实现

YunaiV
1 parent 8585e057
Showing 27 changed files with 78 additions and 89 deletions
yudao-module-bpm/yudao-module-bpm-api/src/main/java/cn/iocoder/yudao/module/bpm/enums/definition/BpmApproveMethodEnum.java
yudao-module-bpm/yudao-module-bpm-api/src/main/java/cn/iocoder/yudao/module/bpm/enums/definition/BpmFieldPermissionEnum.java
yudao-module-bpm/yudao-module-bpm-api/src/main/java/cn/iocoder/yudao/module/bpm/enums/definition/BpmUserTaskRejectHandlerType.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/definition/BpmModelController.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/definition/vo/model/simple/BpmSimpleModelNodeVO.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/controller/admin/definition/vo/model/simple/BpmSimpleModelUpdateReqVO.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/candidate/strategy/BpmTaskCandidateStartUserStrategy.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/custom/delegate/CopyUserDelegate.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/custom/delegate/MultiInstanceServiceTaskDelegate.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/custom/expression/CompleteByRejectCountExpression.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/el/VariableConvertByTypeExpressionFunction.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/enums/BpmnModelConstants.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/framework/flowable/core/listener/BpmTimerFiredEventListener.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/mq/producer/task/TodoTaskReminderProducer.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/util/BpmnFormUtils.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/util/BpmnModelUtils.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/flowable/core/util/SimpleModelUtils.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/definition/BpmModelService.java
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/service/definition/BpmModelServiceImpl.java
@@ -4,7 +4,6 @@ import cn.hutool.core.util.ArrayUtil;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
-// TODO @芋艿：审批方式的名字，可能要看下；
 /**
  * BPM 多人审批方式的枚举
  *
@@ -13,6 +13,7 @@ import lombok.Getter;
 @AllArgsConstructor
 public enum BpmFieldPermissionEnum {
+    // TODO @jason：这个顺序要不要改下，和页面保持一致；只读（1）、编辑（2）、隐藏（3）
     WRITE(1, "可编辑"),
     READ(2, "只读"),
     NONE(3, "隐藏");
@@ -13,8 +13,10 @@ import lombok.Getter;
 @AllArgsConstructor
 public enum BpmUserTaskRejectHandlerType {
+    // TODO @jason：是不是收敛成 2 个：FINISH_PROCESS => 1. 直接结束流程；RETURN_PRE_USER_TASK => 2. 驳回到指定节点（RETURN_USER_TASK【去掉 PRE】）
     FINISH_PROCESS(1, "终止流程"),
     RETURN_PRE_USER_TASK(2, "驳回到指定任务节点"),
+
     FINISH_PROCESS_BY_REJECT_NUMBER(3, "按拒绝人数终止流程"), // 用于会签
     FINISH_TASK(4, "结束任务"); // 待实现，可能会用于意见分支
@@ -24,4 +26,5 @@ public enum BpmUserTaskRejectHandlerType {
     public static BpmUserTaskRejectHandlerType typeOf(Integer type) {
         return ArrayUtil.firstMatch(item -> item.getType().equals(type), values());
     }
+
 }
@@ -149,6 +149,7 @@ public class BpmModelController {
     // ========== 仿钉钉/飞书的精简模型 =========
+    // TODO @jason：modelId => id 哈。一般属于自己的模块，可以简化命名。
     @GetMapping("/simple/get")
     @Operation(summary = "获得仿钉钉流程设计模型")
     @Parameter(name = "modelId", description = "流程模型编号", required = true, example = "a2c5eee0-eb6c-11ee-abf4-0c37967c420a")
@@ -43,6 +43,7 @@ public class BpmSimpleModelNodeVO {
     @Schema(description = "节点的属性")
     private Map<String, Object> attributes; // TODO @jason：建议是字段分拆下；类似说：
+    // TODO @jason：看看是不是可以简化；
     /**
      * 附加节点 Id, 该节点不从前端传入。 由程序生成. 由于当个节点无法完成功能。 需要附加节点来完成。
      * 例如： 会签时需要按拒绝人数来终止流程。 需要 userTask + ServiceTask 两个节点配合完成。 serviceTask 由后端生成。
@@ -52,12 +53,13 @@ public class BpmSimpleModelNodeVO {
     // Map<String, Integer> formPermissions; 表单权限；仅发起、审批、抄送节点会使用
     // Integer approveMethod; 审批方式；仅审批节点会使用
-    // TODO @jason 后面和前端一起调整一下
-    // TODO @芋艿：审批人的选择；
-    // TODO @芋艿：没有人的策略？
-    // TODO @芋艿：审批拒绝的策略？
-    // TODO @芋艿：配置的可操作列表？
-    // TODO @芋艿：超时配置；要支持指定时间点、指定时间间隔；
+    // TODO @jason 后面和前端一起调整一下；下面的 ①、②、③ 是优先级
+    // TODO @芋艿：① 审批人的选择；
+    // TODO @芋艿：⑥ 没有人的策略？
+    // TODO @芋艿：② 审批拒绝的策略？
+    // TODO @芋艿：③ 配置的可操作列表？（操作权限）
+    // TODO @芋艿：④ 表单的权限列表？
+    // TODO @芋艿：⑨ 超时配置；要支持指定时间点、指定时间间隔；
     // TODO @芋艿：条件；建议可以固化的一些选项；然后有个表达式兜底；要支持
 }
@@ -11,6 +11,7 @@ import lombok.Data;
 @Data
 public class BpmSimpleModelUpdateReqVO {
+    // TODO @jason：=> id
     @Schema(description = "流程模型编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "1")
     @NotEmpty(message = "流程模型编号不能为空")
     private String modelId; // 对应 Flowable act_re_model 表 ID_ 字段
@@ -28,9 +28,6 @@ public class BpmTaskCandidateStartUserStrategy implements BpmTaskCandidateStrate
         return BpmTaskCandidateStrategyEnum.START_USER;
     }
-    /**
-     * 无需校验参数
-     */
     @Override
     public void validateParam(String param) {}
@@ -40,11 +37,9 @@ public class BpmTaskCandidateStartUserStrategy implements BpmTaskCandidateStrate
         return SetUtils.asSet(Long.valueOf(startUserId));
     }
-    /**
-     * 不需要参数
-     */
     @Override
     public boolean isParamRequired() {
         return false;
     }
+
 }
 package cn.iocoder.yudao.module.bpm.framework.flowable.core.custom.delegate;
+import cn.hutool.core.collection.CollUtil;
 import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.BpmTaskCandidateInvoker;
 import cn.iocoder.yudao.module.bpm.service.task.BpmProcessInstanceCopyService;
 import jakarta.annotation.Resource;
@@ -10,23 +11,29 @@ import org.springframework.stereotype.Service;
 import java.util.Set;
+// TODO @jason：类名可以改成 BpmCopyTaskDelegate
 /**
- * 处理抄送用户的代理
+ * 处理抄送用户的 {@link JavaDelegate} 的实现类
  *
  * @author jason
  */
-@Service
+@Service // TODO @jason：这种注解，建议用 @Component
 public class CopyUserDelegate implements JavaDelegate  {
     @Resource
     private BpmTaskCandidateInvoker taskCandidateInvoker;
+
     @Resource
     private BpmProcessInstanceCopyService processInstanceCopyService;
     @Override
     public void execute(DelegateExecution execution) {
-        // TODO @芋艿：可能要考虑，系统抄送，没有 taskId 的情况。
+        // 1. 获得抄送人
         Set<Long> userIds = taskCandidateInvoker.calculateUsers(execution);
+        if (CollUtil.isEmpty(userIds)) {
+            return;
+        }
+        // 2. 执行抄送
         FlowElement currentFlowElement = execution.getCurrentFlowElement();
         processInstanceCopyService.createProcessInstanceCopy(userIds, execution.getProcessInstanceId(),
                 currentFlowElement.getId(), currentFlowElement.getName());
@@ -10,6 +10,7 @@ import org.flowable.engine.delegate.DelegateExecution;
 import org.flowable.engine.delegate.JavaDelegate;
 import org.springframework.stereotype.Component;
+// TODO @jason：微信已经讨论，简化哈
 /**
  * 处理会签 Service Task 代理
  *
@@ -25,7 +26,7 @@ public class MultiInstanceServiceTaskDelegate implements JavaDelegate {
     public void execute(DelegateExecution execution) {
         String attachUserTaskId = BpmnModelUtils.parseExtensionElement(execution.getCurrentFlowElement(),
-                BpmnModelConstants.SERVICE_TASK_ATTACH_USER_TASK_ID);
+                BpmnModelConstants.SERVICE_TASK_ATTACH_USER_TASK_ID); // TODO @jason：上面不需要加空行哈；
         Assert.notNull(attachUserTaskId, "附属的用户任务 Id 不能为空");
         // 获取会签任务是否被拒绝
         Boolean userTaskRejected = execution.getVariable(String.format("%s_reject", attachUserTaskId), Boolean.class);
@@ -19,6 +19,7 @@ import static cn.iocoder.yudao.module.bpm.enums.definition.BpmApproveMethodEnum.
 import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants.USER_TASK_APPROVE_METHOD;
 import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants.USER_TASK_APPROVE_RATIO;
+// TODO @jason：微信已经讨论，简化哈
 /**
  * 按拒绝人数计算会签的完成条件的流程表达式实现
  *
@@ -4,6 +4,7 @@ import org.flowable.common.engine.api.variable.VariableContainer;
 import org.flowable.common.engine.impl.el.function.AbstractFlowableVariableExpressionFunction;
 import org.springframework.stereotype.Component;
+// TODO @jason：这个自定义转换的原因是啥呀？
 /**
  * 根据流程变量 variable 的类型, 转换参数的值
  *
@@ -40,6 +40,7 @@ public interface BpmnModelConstants {
      */
     String USER_TASK_TIMEOUT_HANDLER_ACTION = "timeoutAction";
+    // TODO @jason：1）是不是上面的 timeoutAction 改成 timeoutHandler；2）rejectHandlerType 改成 rejectHandler 哇？
     /**
      * BPMN ExtensionElement 的扩展属性，用于标记用户任务拒绝处理类型
      */
@@ -73,6 +73,7 @@ public class BpmTaskEventListener extends AbstractFlowableEngineEventListener {
         });
     }
+    // TODO @jason：这块如果不需要，可以删除掉~~~
 //    @Override
 //    protected void activityMessageReceived(FlowableMessageEvent event) {
 //        BpmnModel bpmnModel = bpmModelService.getBpmnModelByDefinitionId(event.getProcessDefinitionId());
@@ -29,6 +29,7 @@ import org.springframework.stereotype.Component;
 import java.util.List;
 import java.util.Set;
+// TODO @芋艿：这块需要仔细再瞅瞅
 /**
  * 监听定时器触发事件
  *
@@ -96,7 +97,6 @@ public class BpmTimerFiredEventListener extends AbstractFlowableEngineEventListe
                     BpmTaskApproveReqVO req = new BpmTaskApproveReqVO().setId(task.getId())
                             .setReason("超时系统自动同意");
                     bpmTaskService.approveTask(Long.parseLong(task.getAssignee()), req);
-
                 }
                 // 自动拒绝
                 if (userTaskTimeoutAction == BpmUserTaskTimeoutActionEnum.AUTO_REJECT) {
@@ -7,6 +7,7 @@ import org.springframework.context.ApplicationContext;
 import org.springframework.stereotype.Component;
 import org.springframework.validation.annotation.Validated;
+// TODO @jason：建议直接调用 BpmMessageService 哈；更简化一点~
 /**
  * 待办任务提醒 Producer
  *
@@ -22,4 +23,5 @@ public class TodoTaskReminderProducer {
     public void sendReminderMessage(@Valid TodoTaskReminderMessage message) {
         applicationContext.publishEvent(message);
     }
+
 }
-package cn.iocoder.yudao.module.bpm.framework.flowable.core.simple;
+package cn.iocoder.yudao.module.bpm.framework.flowable.core.simplemodel;
 import lombok.Data;
-package cn.iocoder.yudao.module.bpm.framework.flowable.core.simple;
+package cn.iocoder.yudao.module.bpm.framework.flowable.core.simplemodel;
 import cn.iocoder.yudao.module.bpm.enums.definition.BpmApproveMethodEnum;
 import cn.iocoder.yudao.module.bpm.enums.definition.BpmUserTaskRejectHandlerType;
@@ -18,12 +18,11 @@ public class SimpleModelUserTaskConfig {
     /**
      * 候选人策略
      */
-    private  Integer candidateStrategy;
-
+    private Integer candidateStrategy;
     /**
      * 候选人参数
      */
-    private  String candidateParam;
+    private String candidateParam;
     /**
      * 字段权限
@@ -34,11 +33,11 @@ public class SimpleModelUserTaskConfig {
      * 审批方式 {@link BpmApproveMethodEnum }
      */
     private  Integer approveMethod;
-
     /**
      * 通过比例  当审批方式为 多人会签(按通过比例) 需设置
      */
     private Integer approveRatio;
+
     /**
      * 超时处理
      */
@@ -15,7 +15,7 @@ import java.util.Map;
 import static cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants.FORM_FIELD_PERMISSION_ELEMENT_FIELD_ATTRIBUTE;
-
+// TODO @芋艿：这块去研究下！
 /**
  *  Bpmn 流程表单相关工具方法
  *
@@ -27,6 +27,7 @@ public class BpmnModelUtils {
         // TODO @芋艿 尝试从 ExtensionElement 取. 后续相关扩展是否都可以 存 extensionElement。 如表单权限。 按钮权限
         if (candidateStrategy == null) {
             ExtensionElement element = CollUtil.getFirst(userTask.getExtensionElements().get(BpmnModelConstants.USER_TASK_CANDIDATE_STRATEGY));
+            // TODO @jason：这里可以改成 element != null 看着会简单点 element != null ? NumberUtils.parseInt(element.getElementText()) : null;
             candidateStrategy = NumberUtils.parseInt(Optional.ofNullable(element).map(ExtensionElement::getElementText).orElse(null));
         }
         return candidateStrategy;
@@ -37,6 +38,7 @@ public class BpmnModelUtils {
                 BpmnModelConstants.NAMESPACE, BpmnModelConstants.USER_TASK_CANDIDATE_PARAM);
         if (candidateParam == null) {
             ExtensionElement element = CollUtil.getFirst(userTask.getExtensionElements().get(BpmnModelConstants.USER_TASK_CANDIDATE_PARAM));
+            // TODO @jason：这里可以改成 element != null 看着会简单点 element != null ? element.getElementText() : null;
             candidateParam = Optional.ofNullable(element).map(ExtensionElement::getElementText).orElse(null);
         }
         return candidateParam;
@@ -12,9 +12,9 @@ import cn.iocoder.yudao.module.bpm.enums.definition.BpmApproveMethodEnum;
 import cn.iocoder.yudao.module.bpm.enums.definition.BpmSimpleModeConditionType;
 import cn.iocoder.yudao.module.bpm.enums.definition.BpmSimpleModelNodeType;
 import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmnModelConstants;
-import cn.iocoder.yudao.module.bpm.framework.flowable.core.simple.SimpleModelConditionGroups;
-import cn.iocoder.yudao.module.bpm.framework.flowable.core.simple.SimpleModelUserTaskConfig;
-import cn.iocoder.yudao.module.bpm.framework.flowable.core.simple.SimpleModelUserTaskConfig.RejectHandler;
+import cn.iocoder.yudao.module.bpm.framework.flowable.core.simplemodel.SimpleModelConditionGroups;
+import cn.iocoder.yudao.module.bpm.framework.flowable.core.simplemodel.SimpleModelUserTaskConfig;
+import cn.iocoder.yudao.module.bpm.framework.flowable.core.simplemodel.SimpleModelUserTaskConfig.RejectHandler;
 import org.flowable.bpmn.BpmnAutoLayout;
 import org.flowable.bpmn.model.Process;
 import org.flowable.bpmn.model.*;
@@ -253,33 +253,26 @@ public class SimpleModelUtils {
         return sequenceFlow;
     }
-    // TODO-DONE @jason：要不改成 recursionNode 递归节点，然后把 build 名字让出来，专门用于构建各种 Node
-    // @芋艿 改成了 traverseNodeToBuildFlowNode， 连线的叫 traverseNodeToBuildSequenceFlow
-    // TODO-DONE @jason：node 改成 node，process 改成 process；更符合递归的感觉哈，处理当前节点
+    // TODO @芋艿 改成了 traverseNodeToBuildFlowNode， 连线的叫 traverseNodeToBuildSequenceFlow
     private static void traverseNodeToBuildFlowNode(BpmSimpleModelNodeVO node, Process process) {
         // 判断是否有效节点
-        // TODO-DONE @jason：是不是写个 isValidNode 方法：判断是否为有效节点；
         if (!isValidNode(node)) {
             return;
         }
         BpmSimpleModelNodeType nodeType = BpmSimpleModelNodeType.valueOf(node.getType());
         Assert.notNull(nodeType, "模型节点类型不支持");
-        // TODO-DONE @jason：要不抽个 buildNode 方法，然后返回一个 List<FlowElement>，之后这个方法 addFlowElement；原因是，让当前这个方法，有主干逻辑；不然现在太长了；
         List<FlowElement> flowElements = buildFlowNode(node, nodeType);
         flowElements.forEach(process::addFlowElement);
         // 如果不是网关类型的接口， 并且chileNode为空退出
-        // TODO-DONE @jason：建议这个判断去掉，可以更简洁一点；因为往下走；如果不成功，本身也就会结束哈；主要是，这里多了一个这样的判断，增加了理解成本；
         // 如果是“分支”节点，则递归处理条件
         if (BpmSimpleModelNodeType.isBranchNode(node.getType())
                 && ArrayUtil.isNotEmpty(node.getConditionNodes())) {
-            // TODO-DONE @jason：可以搞成 stream 写成一行哈
             node.getConditionNodes().forEach(item -> traverseNodeToBuildFlowNode(item.getChildNode(), process));
         }
         // 如果有“子”节点，则递归处理子节点
-        // TODO-DONE @jason：这个，是不是不写判断，直接继续调用；因为本身 buildAndAddBpmnFlowNode 就会最开始判断了哈，就不重复判断了；
         traverseNodeToBuildFlowNode(node.getChildNode(), process);
     }
@@ -291,16 +284,13 @@ public class SimpleModelUtils {
         List<FlowElement> list = new ArrayList<>();
         switch (nodeType) {
             case START_NODE: {
-                // TODO-DONE @jason：每个 nodeType，buildXXX 方法要不更明确，并且去掉 Bpmn；
                 // @芋艿 改成 convert 是不是好理解一点
                 StartEvent startEvent = convertStartNode(node);
                 list.add(startEvent);
                 break;
             }
             case APPROVE_NODE: {
-                // TODO-DONE @jason：这个，搞成一个 buildUserTask，然后把下面这 2 种节点，搞在一起实现类；这样 buildNode 里面可以更简洁；
-                // TODO-DONE @jason：这里还有个想法，是不是可以所有的都叫 buildXXXNode，然后里面有一些是 bpmn 相关的构建，叫做 buildBpmnUserTask，用于区分；
-                // @芋艿 改成 convertXXXNode, ， 方面里面使用 buildBpmnXXXNode. 是否更好理解
+                // TODO @芋艿 改成 convertXXXNode, ， 方面里面使用 buildBpmnXXXNode. 是否更好理解
                 // 转换审批节点
                 List<FlowElement> flowElements = convertApproveNode(node);
                 list.addAll(flowElements);
@@ -51,31 +51,6 @@ public interface BpmModelService {
     byte[] getModelBpmnXML(String id);
     /**
-     * 保存流程模型的 BPMN XML
-     *
-     * @param id       编号
-     * @param xmlBytes BPMN XML bytes
-     */
-    // TODO @芋艿：感觉可以不修改这个方法，而是额外加一个方法；传入 id，bpmn，json；
-    void saveModelBpmnXml(String id, byte[] xmlBytes);
-
-    /**
-     * 获得仿钉钉快搭模型的 JSON 数据
-     *
-     * @param id 编号
-     * @return JSON bytes
-     */
-    byte[] getModelSimpleJson(String id);
-
-    /**
-     * 保存仿钉钉快搭模型的 JSON 数据
-     *
-     * @param id        编号
-     * @param jsonBytes JSON bytes
-     */
-    void saveModelSimpleJson(String id, byte[] jsonBytes);
-
-    /**
      * 修改流程模型
      *
      * @param updateReqVO 更新信息
@@ -129,6 +104,6 @@ public interface BpmModelService {
      */
     void updateSimpleModel(@Valid BpmSimpleModelUpdateReqVO reqVO);
-    // TODO @jason：另外个问题，因为是存储到 modelExtra 里，那需要 deploy 存储出快照。和 bpmn xml 一样。目前我想到的，就是存储到 BpmProcessDefinitionInfoDO 加一个 simple_model 字段，text 类型。可以看看还有啥方案？
+    // TODO @jason：另外个问题，因为是存储到 modelExtra 里，那需要 deploy 存储出快照。和 bpmn xml 一样。目前我想到的，就是存储到 BpmProcessDefinitionInfoDO 加一个 simple_model 字段，text 类型。可以看看还有啥方案？【重要】
 }
@@ -107,7 +107,7 @@ public class BpmModelServiceImpl implements BpmModelService {
         // 保存流程定义
         repositoryService.saveModel(model);
         // 保存 BPMN XML
-        saveModelBpmnXml(model.getId(), StrUtil.utf8Bytes(bpmnXml));
+        saveModelBpmnXml(model.getId(), bpmnXml);
         return model.getId();
     }
@@ -125,7 +125,7 @@ public class BpmModelServiceImpl implements BpmModelService {
         // 更新模型
         repositoryService.saveModel(model);
         // 更新 BPMN XML
-        saveModelBpmnXml(model.getId(), StrUtil.utf8Bytes(updateReqVO.getBpmnXml()));
+        saveModelBpmnXml(model.getId(), updateReqVO.getBpmnXml());
     }
     @Override
@@ -218,23 +218,24 @@ public class BpmModelServiceImpl implements BpmModelService {
         if (model == null) {
             throw exception(MODEL_NOT_EXISTS);
         }
-        // 通过 ACT_RE_MODEL 表 EDITOR_SOURCE_EXTRA_VALUE_ID_  获取 仿钉钉快搭模型的JSON 数据
+        // 通过 ACT_RE_MODEL 表 EDITOR_SOURCE_EXTRA_VALUE_ID_ ，获取仿钉钉快搭模型的 JSON 数据
         byte[] jsonBytes = getModelSimpleJson(model.getId());
         return JsonUtils.parseObject(jsonBytes, BpmSimpleModelNodeVO.class);
     }
     @Override
     public void updateSimpleModel(BpmSimpleModelUpdateReqVO reqVO) {
-        // 1.1 校验流程模型存在
+        // 1. 校验流程模型存在
         Model model = getModel(reqVO.getModelId());
         if (model == null) {
             throw exception(MODEL_NOT_EXISTS);
         }
-        // 1.2 JSON 转换成 bpmnModel
+
+        // 2.1 JSON 转换成 bpmnModel
         BpmnModel bpmnModel = SimpleModelUtils.buildBpmnModel(model.getKey(), model.getName(), reqVO.getSimpleModel());
-        // 2.1 保存 Bpmn XML
-        saveModelBpmnXml(model.getId(), StrUtil.utf8Bytes(BpmnModelUtils.getBpmnXml(bpmnModel)));
-        // 2.2 保存 JSON 数据
+        // 2.2 保存 Bpmn XML
+        saveModelBpmnXml(model.getId(), BpmnModelUtils.getBpmnXml(bpmnModel));
+        // 2.3 保存 JSON 数据
         saveModelSimpleJson(model.getId(), JsonUtils.toJsonByte(reqVO.getSimpleModel()));
     }
@@ -266,21 +267,18 @@ public class BpmModelServiceImpl implements BpmModelService {
         }
     }
-    @Override
-    public void saveModelBpmnXml(String id,  byte[] xmlBytes) {
-        if (ArrayUtil.isEmpty(xmlBytes)) {
+    private void saveModelBpmnXml(String id, String bpmnXml) {
+        if (StrUtil.isEmpty(bpmnXml)) {
             return;
         }
-        repositoryService.addModelEditorSource(id, xmlBytes);
+        repositoryService.addModelEditorSource(id, StrUtil.utf8Bytes(bpmnXml));
     }
-    @Override
-    public byte[] getModelSimpleJson(String id) {
+    private byte[] getModelSimpleJson(String id) {
         return repositoryService.getModelEditorSourceExtra(id);
     }
-    @Override
-    public void saveModelSimpleJson(String id, byte[] jsonBytes) {
+    private void saveModelSimpleJson(String id, byte[] jsonBytes) {
         if (ArrayUtil.isEmpty(jsonBytes)) {
             return;
         }
@@ -13,6 +13,8 @@ import java.util.Collection;
  */
 public interface BpmProcessInstanceCopyService {
+    // TODO @jason：要不把 createProcessInstanceCopy 搞 2 个方法，一个方法参数是之前的 userIds、taskId；一个方法是现在 userIds、processInstanceId、taskId、taskName；
+
     /**
      * 流程实例的抄送
      *
@@ -127,23 +127,23 @@ public interface BpmProcessInstanceService {
     void updateProcessInstanceWhenCancel(FlowableCancelledEvent event);
     /**
-     * 更新 ProcessInstance 拓展记录为完成
+     * 更新 ProcessInstance 为完成
      *
      * @param instance 流程任务
      */
     void updateProcessInstanceWhenApprove(ProcessInstance instance);
     /**
-     * 更新 ProcessInstance 拓展记录为不通过
+     * 更新 ProcessInstance 为不通过
      *
      * @param id     流程编号
-     * @param currentActivityId  当前的活动Id
+     * @param currentActivityId  当前的活动编号
      * @param reason 理由。例如说，审批不通过时，需要传递该值
      */
     void updateProcessInstanceReject(String id, String currentActivityId,  String reason);
     /**
-     * 当流程结束时候。 更新 ProcessInstance
+     * 当流程结束时候，更新 ProcessInstance 为通过
      *
      * @param instance 流程任务
      */
-package cn.iocoder.yudao.module.bpm.service.task;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.lang.Assert;
import cn.hutool.core.util.ArrayUtil;
import cn.hutool.core.util.StrUtil;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.common.util.date.DateUtils;
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.task.vo.instance.BpmProcessInstanceCancelReqVO;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmProcessInstanceCreateReqVO;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmProcessInstancePageReqVO;
import cn.iocoder.yudao.module.bpm.convert.task.BpmProcessInstanceConvert;
import cn.iocoder.yudao.module.bpm.enums.task.BpmDeleteReasonEnum;
import cn.iocoder.yudao.module.bpm.enums.task.BpmProcessInstanceStatusEnum;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.strategy.BpmTaskCandidateStartUserSelectStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmConstants;
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.service.definition.BpmProcessDefinitionService;
import cn.iocoder.yudao.module.bpm.service.message.BpmMessageService;
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.model.BpmnModel;
import org.flowable.bpmn.model.EndEvent;
import org.flowable.bpmn.model.UserTask;
import org.flowable.engine.HistoryService;
import org.flowable.engine.RuntimeService;
import org.flowable.engine.delegate.event.FlowableCancelledEvent;
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.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.module.bpm.enums.ErrorCodeConstants.*;

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

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

    @Resource
    private BpmProcessDefinitionService processDefinitionService;
    @Resource
    private BpmMessageService messageService;

    @Resource
    private AdminUserApi adminUserApi;

    @Resource
    private BpmProcessInstanceEventPublisher processInstanceEventPublisher;

    @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.getProcessDefinitionId())) {
            processInstanceQuery.processDefinitionId("%" + pageReqVO.getProcessDefinitionId() + "%");
        }
        if (StrUtil.isNotEmpty(pageReqVO.getCategory())) {
            processInstanceQuery.processDefinitionCategory(pageReqVO.getCategory());
        }
        if (pageReqVO.getStatus() != null) {
            processInstanceQuery.variableValueEquals(BpmConstants.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);
    }

    @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);
        }
        // 1.2 校验发起人自选审批人
        validateStartUserSelectAssignees(definition, startUserSelectAssignees);

        // 2. 创建流程实例
        if (variables == null) {
            variables = new HashMap<>();
        }
        FlowableUtils.filterProcessInstanceFormVariable(variables); // 过滤一下，避免 ProcessInstance 系统级的变量被占用
        variables.put(BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS, // 流程实例状态：审批中
                BpmProcessInstanceStatusEnum.RUNNING.getStatus());
        if (CollUtil.isNotEmpty(startUserSelectAssignees)) {
            variables.put(BpmConstants.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. 通过删除流程实例，实现流程实例的取消,
        // 删除流程实例，正则执行任务 ACT_RU_TASK. 任务会被删除。
        deleteProcessInstance(cancelReqVO.getId(),
                BpmDeleteReasonEnum.CANCEL_PROCESS_INSTANCE_BY_START_USER.format(cancelReqVO.getReason()));

        // 3. 进一步的处理，交给 updateProcessInstanceCancel 方法
    }

    @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);
        }
        // 1.2 管理员取消，不用校验是否为自己的
        AdminUserRespDTO user = adminUserApi.getUser(userId);

        // 2. 通过删除流程实例，实现流程实例的取消,
        // 删除流程实例，正则执行任务 ACT_RU_TASK. 任务会被删除。
        deleteProcessInstance(cancelReqVO.getId(),
                BpmDeleteReasonEnum.CANCEL_PROCESS_INSTANCE_BY_ADMIN.format(user.getNickname(), cancelReqVO.getReason()));

        // 3. 进一步的处理，交给 updateProcessInstanceCancel 方法
    }

    @Override
    public void updateProcessInstanceWhenCancel(FlowableCancelledEvent event) {
//        // 1. 判断是否为 Reject 不通过。如果是，则不进行更新. 这种情况不会发生了。 拒绝时候不会删除流程
//        // 因为，updateProcessInstanceReject 方法（审批不通过），已经进行更新了
//        if (BpmDeleteReasonEnum.isRejectReason((String) event.getCause())) {
//            return;
//        }

        // 1. 更新流程实例 status
        runtimeService.setVariable(event.getProcessInstanceId(), BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.CANCEL.getStatus());

        // 2. 发送流程实例的状态事件
        // 注意：此时如果去查询 ProcessInstance 的话，字段是不全的，所以去查询了 HistoricProcessInstance
        HistoricProcessInstance processInstance = getHistoricProcessInstance(event.getProcessInstanceId());
        // 发送流程实例的状态事件
        processInstanceEventPublisher.sendProcessInstanceResultEvent(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceStatusEvent(this, processInstance, BpmProcessInstanceStatusEnum.CANCEL.getStatus()));
    }

    @Override
    public void updateProcessInstanceWhenApprove(ProcessInstance instance) {

        // 1. 更新流程实例 status
        runtimeService.setVariable(instance.getId(), BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.APPROVE.getStatus());

        // 2. 发送流程被【通过】的消息
        messageService.sendMessageWhenProcessInstanceApprove(BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceApproveMessage(instance));

        // 3. 发送流程实例的状态事件
        // 注意：此时如果去查询 ProcessInstance 的话，字段是不全的，所以去查询了 HistoricProcessInstance
        HistoricProcessInstance processInstance = getHistoricProcessInstance(instance.getId());
        processInstanceEventPublisher.sendProcessInstanceResultEvent(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceStatusEvent(this, processInstance, BpmProcessInstanceStatusEnum.APPROVE.getStatus()));
    }

    @Override
    @Transactional(rollbackFor = Exception.class)
    public void updateProcessInstanceReject(String id, String currentActivityId, String reason) {
        // 1. 更新流程实例 status
        runtimeService.setVariable(id, BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS, BpmProcessInstanceStatusEnum.REJECT.getStatus());

        // 2. 跳转到流程结束 EndEvent 节点, 结束流程
        ProcessInstance processInstance = getProcessInstance(id);
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processInstance.getProcessDefinitionId());
        EndEvent endEvent = BpmnModelUtils.getEndEvent(bpmnModel);
        Assert.notNull(endEvent, "结束节点不能为空");
        runtimeService.createChangeActivityStateBuilder()
                .processInstanceId(id)
                .moveActivityIdTo(currentActivityId,  // 当前节点
                        endEvent.getId()) // 结束节点
                .changeState();

        // 3. 发送流程被【不通过】的消息
        messageService.sendMessageWhenProcessInstanceReject(BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceRejectMessage(processInstance, reason));

        // 4. 发送流程实例的状态事件
        processInstanceEventPublisher.sendProcessInstanceResultEvent(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceStatusEvent(this, processInstance, BpmProcessInstanceStatusEnum.REJECT.getStatus()));
    }

    @Override
    public void updateProcessInstanceWhenCompleted(ProcessInstance instance) {
        Integer status = (Integer) instance.getProcessVariables().get(BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS);
        // 当流程状态还是审批状态中, 更新为审批通过
        if (Objects.equals(status, BpmProcessInstanceStatusEnum.RUNNING.getStatus())) {
            updateProcessInstanceWhenApprove(instance);
        }
        // 审批不通过状态。已经在 updateProcessInstanceReject 处理
    }

    private void deleteProcessInstance(String id, String reason) {
        runtimeService.deleteProcessInstance(id, reason);
    }

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

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.lang.Assert;
import cn.hutool.core.util.ArrayUtil;
import cn.hutool.core.util.StrUtil;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.common.util.date.DateUtils;
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.task.vo.instance.BpmProcessInstanceCancelReqVO;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmProcessInstanceCreateReqVO;
import cn.iocoder.yudao.module.bpm.controller.admin.task.vo.instance.BpmProcessInstancePageReqVO;
import cn.iocoder.yudao.module.bpm.convert.task.BpmProcessInstanceConvert;
import cn.iocoder.yudao.module.bpm.enums.task.BpmDeleteReasonEnum;
import cn.iocoder.yudao.module.bpm.enums.task.BpmProcessInstanceStatusEnum;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.strategy.BpmTaskCandidateStartUserSelectStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmConstants;
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.service.definition.BpmProcessDefinitionService;
import cn.iocoder.yudao.module.bpm.service.message.BpmMessageService;
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.model.BpmnModel;
import org.flowable.bpmn.model.EndEvent;
import org.flowable.bpmn.model.UserTask;
import org.flowable.engine.HistoryService;
import org.flowable.engine.RuntimeService;
import org.flowable.engine.delegate.event.FlowableCancelledEvent;
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.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.module.bpm.enums.ErrorCodeConstants.*;

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

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

    @Resource
    private BpmProcessDefinitionService processDefinitionService;
    @Resource
    private BpmMessageService messageService;

    @Resource
    private AdminUserApi adminUserApi;

    @Resource
    private BpmProcessInstanceEventPublisher processInstanceEventPublisher;

    @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.getProcessDefinitionId())) {
            processInstanceQuery.processDefinitionId("%" + pageReqVO.getProcessDefinitionId() + "%");
        }
        if (StrUtil.isNotEmpty(pageReqVO.getCategory())) {
            processInstanceQuery.processDefinitionCategory(pageReqVO.getCategory());
        }
        if (pageReqVO.getStatus() != null) {
            processInstanceQuery.variableValueEquals(BpmConstants.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);
    }

    @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);
        }
        // 1.2 校验发起人自选审批人
        validateStartUserSelectAssignees(definition, startUserSelectAssignees);

        // 2. 创建流程实例
        if (variables == null) {
            variables = new HashMap<>();
        }
        FlowableUtils.filterProcessInstanceFormVariable(variables); // 过滤一下，避免 ProcessInstance 系统级的变量被占用
        variables.put(BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS, // 流程实例状态：审批中
                BpmProcessInstanceStatusEnum.RUNNING.getStatus());
        if (CollUtil.isNotEmpty(startUserSelectAssignees)) {
            variables.put(BpmConstants.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. 通过删除流程实例，实现流程实例的取消,
        // 删除流程实例，正则执行任务 ACT_RU_TASK. 任务会被删除。
        deleteProcessInstance(cancelReqVO.getId(),
                BpmDeleteReasonEnum.CANCEL_PROCESS_INSTANCE_BY_START_USER.format(cancelReqVO.getReason()));

        // 3. 进一步的处理，交给 updateProcessInstanceCancel 方法
    }

    @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);
        }
        // 1.2 管理员取消，不用校验是否为自己的
        AdminUserRespDTO user = adminUserApi.getUser(userId);

        // 2. 通过删除流程实例，实现流程实例的取消,
        // 删除流程实例，正则执行任务 ACT_RU_TASK. 任务会被删除。
        deleteProcessInstance(cancelReqVO.getId(),
                BpmDeleteReasonEnum.CANCEL_PROCESS_INSTANCE_BY_ADMIN.format(user.getNickname(), cancelReqVO.getReason()));

        // 3. 进一步的处理，交给 updateProcessInstanceCancel 方法
    }

    @Override
    public void updateProcessInstanceWhenCancel(FlowableCancelledEvent event) {
//        // 1. 判断是否为 Reject 不通过。如果是，则不进行更新. 这种情况不会发生了。 拒绝时候不会删除流程
//        // 因为，updateProcessInstanceReject 方法（审批不通过），已经进行更新了
//        if (BpmDeleteReasonEnum.isRejectReason((String) event.getCause())) {
//            return;
//        }

        // 1. 更新流程实例 status
        runtimeService.setVariable(event.getProcessInstanceId(), BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.CANCEL.getStatus());

        // 2. 发送流程实例的状态事件
        // 注意：此时如果去查询 ProcessInstance 的话，字段是不全的，所以去查询了 HistoricProcessInstance
        HistoricProcessInstance processInstance = getHistoricProcessInstance(event.getProcessInstanceId());
        // 发送流程实例的状态事件
        processInstanceEventPublisher.sendProcessInstanceResultEvent(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceStatusEvent(this, processInstance, BpmProcessInstanceStatusEnum.CANCEL.getStatus()));
    }

    @Override
    public void updateProcessInstanceWhenApprove(ProcessInstance instance) {
        // 1. 更新流程实例 status
        runtimeService.setVariable(instance.getId(), BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS,
                BpmProcessInstanceStatusEnum.APPROVE.getStatus());

        // 2. 发送流程被【通过】的消息
        messageService.sendMessageWhenProcessInstanceApprove(BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceApproveMessage(instance));

        // 3. 发送流程实例的状态事件
        // 注意：此时如果去查询 ProcessInstance 的话，字段是不全的，所以去查询了 HistoricProcessInstance
        HistoricProcessInstance processInstance = getHistoricProcessInstance(instance.getId());
        processInstanceEventPublisher.sendProcessInstanceResultEvent(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceStatusEvent(this, processInstance, BpmProcessInstanceStatusEnum.APPROVE.getStatus()));
    }

    @Override
    @Transactional(rollbackFor = Exception.class)
    public void updateProcessInstanceReject(String id, String currentActivityId, String reason) {
        // 1. 更新流程实例 status
        runtimeService.setVariable(id, BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS, BpmProcessInstanceStatusEnum.REJECT.getStatus());

        // 2. 跳转到流程结束 EndEvent 节点，结束流程
        // TODO @jason：需要测试下，如果这么走。当前其它审批任务，会不会结束，以及它们的状态是什么？！【重要】
        ProcessInstance processInstance = getProcessInstance(id);
        BpmnModel bpmnModel = processDefinitionService.getProcessDefinitionBpmnModel(processInstance.getProcessDefinitionId());
        EndEvent endEvent = BpmnModelUtils.getEndEvent(bpmnModel);
        Assert.notNull(endEvent, "结束节点不能为空");
        runtimeService.createChangeActivityStateBuilder()
                .processInstanceId(id)
                .moveActivityIdTo(currentActivityId, endEvent.getId()) // 当前节点 => 结束节点
                .changeState();

        // 3. 发送流程被【不通过】的消息
        messageService.sendMessageWhenProcessInstanceReject(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceRejectMessage(processInstance, reason));

        // 4. 发送流程实例的状态事件
        processInstanceEventPublisher.sendProcessInstanceResultEvent(
                BpmProcessInstanceConvert.INSTANCE.buildProcessInstanceStatusEvent(this, processInstance, BpmProcessInstanceStatusEnum.REJECT.getStatus()));
    }

    @Override
    public void updateProcessInstanceWhenCompleted(ProcessInstance instance) {
        Integer status = (Integer) instance.getProcessVariables().get(BpmConstants.PROCESS_INSTANCE_VARIABLE_STATUS);
        // 当流程状态还是审批状态中, 更新为审批通过
        if (Objects.equals(status, BpmProcessInstanceStatusEnum.RUNNING.getStatus())) {
            updateProcessInstanceWhenApprove(instance);
        }
        // 审批不通过状态。已经在 updateProcessInstanceReject 处理
    }

    private void deleteProcessInstance(String id, String reason) {
        runtimeService.deleteProcessInstance(id, reason);
    }

}
 \ No newline at end of file
@@ -129,6 +129,7 @@ public interface BpmTaskService {
      */
     Task getTask(String id);
+    // TODO @jason：jason：这个貌似可以去掉了。
     /**
      * 根据条件查询已经分配的用户任务列表
      * @param processInstanceId 流程实例编号，不允许为空
@@ -335,14 +335,18 @@ public class BpmTaskServiceImpl implements BpmTaskService {
         // 2.2 添加评论
         taskService.addComment(task.getId(), task.getProcessInstanceId(), BpmCommentTypeEnum.REJECT.getType(),
                 BpmCommentTypeEnum.REJECT.formatComment(reqVO.getReason()));
+
         // 3.1 解析用户任务的拒绝处理类型
         BpmnModel bpmnModel = bpmModelService.getBpmnModelByDefinitionId(task.getProcessDefinitionId());
+        // TODO @jason：342 到 344 最好抽象一个方法出来哈。放在 BpmnModelUtils，参照类似 parseCandidateStrategy
         UserTask flowElement = (UserTask) BpmnModelUtils.getFlowElementById(bpmnModel, task.getTaskDefinitionKey());
         Integer rejectHandlerType = NumberUtils.parseInt(BpmnModelUtils.parseExtensionElement(flowElement, USER_TASK_REJECT_HANDLER_TYPE));
         BpmUserTaskRejectHandlerType userTaskRejectHandlerType = BpmUserTaskRejectHandlerType.typeOf(rejectHandlerType);
-        // 3.2 类型为驳回到指定的任务节点
+        // 3.2 类型为驳回到指定的任务节点 TODO @jason：下面这种判断，最好是 JSON
         if (userTaskRejectHandlerType == BpmUserTaskRejectHandlerType.RETURN_PRE_USER_TASK) {
+            // TODO @jason：348 最好抽象一个方法出来哈。放在 BpmnModelUtils，参照类似 parseCandidateStrategy
             String returnTaskId = BpmnModelUtils.parseExtensionElement(flowElement, USER_TASK_REJECT_RETURN_TASK_ID);
+            // TODO @jason：这里如果找不到，直接抛出系统异常；因为说白了，已经不是业务异常啦。
             if (returnTaskId == null) {
                 throw exception(TASK_RETURN_NOT_ASSIGN_TARGET_TASK_ID);
             }
@@ -351,6 +355,7 @@ public class BpmTaskServiceImpl implements BpmTaskService {
             returnTask(userId, returnReq);
             return;
         } else if (userTaskRejectHandlerType == BpmUserTaskRejectHandlerType.FINISH_PROCESS_BY_REJECT_NUMBER) {
+            // TODO @jason：微信沟通，去掉类似的逻辑；
             // 3.3 按拒绝人数终止流程
             if (!flowElement.hasMultiInstanceLoopCharacteristics()) {
                 log.error("[rejectTask] 按拒绝人数终止流程类型,只能用于会签任务. 当前任务【{}】不是会签任务", task.getId());
@@ -362,7 +367,8 @@ public class BpmTaskServiceImpl implements BpmTaskService {
             return;
         }
         // 3.4 其他情况 终止流程。
-        processInstanceService.updateProcessInstanceReject(instance.getProcessInstanceId(), task.getTaskDefinitionKey(),  reqVO.getReason());
+        processInstanceService.updateProcessInstanceReject(instance.getProcessInstanceId(),
+                task.getTaskDefinitionKey(), reqVO.getReason());
     }
     /**