update - 更新工程说明

README.md

@@ -24,6 +24,26 @@
 - flw_*：Flowable 新版本扩展功能相关的表，流程迁移的表。
 ```
 
+### 2.1 本工程常用的库表
+
+```text
+// 运行时(仅保存运行中的流程相关数据)
+act_ru_execution (执行中的实体)
+act_ru_task (执行中的任务)
+act_ru_variable (执行中的变量)
+
+// 元数据配置信息
+act_re_model (流程模型)
+act_re_procdef (流程定义)
+act_re_deployment (流程部署)
+
+// 历史数据 (运行时产生的数据也会及时写入历史)
+act_hi_procinst (历史的流程实例)
+act_hi_taskinst (历史的任务实例)
+act_hi_varinst (历史的变量实例)
+
+act_ge_bytearray (很多元数据)
+```
 ## 3.国内工作流常用操作的名称解释
 
 | 流程操作  | 描述                                                                                                           |
@@ -45,7 +65,245 @@
 | 交接    | 	流程管理员权限，管理员将离职或换岗员工的待执行、待领取、代办他人、委托他人代办的任务转交给接管人，并删除与该员工相关的委托代理关系。交接员工所有直接参与的流  程实例中对应的参与者将自动由系统修改为接管人。(强制) |
 | 暂存    | 	复杂表单，一次性填写不完，需要保存草稿功能，开始节点的暂存                                                                               |
 
-已完成:
+## 4. 如何配置一个流程?
+
+> 流程的运行依赖一种规则,得让引擎知道何时开始执行流程? 何时终止? 如何识别和控制每个步骤该怎么处理? 执行过程中如何走向不同的路径?
+> 比如: 我们常见的需求, 某个节点需要会签/或签, 或者某个节点需要判断条件是否执行该步骤等等.
+>
+> 以上这些规则都需要再创建流程实例时, 提前就告诉引擎, 且运行过程和步骤中是不可变的. 引擎自己也未提供相应能力.
+>
+> 这种规则在 Flowable 的世界中,是以 BPMN2.0 协议规则进行编写和持久化.
+
+## 4.1 简单识别流程定义
+
+![流程定义 png](imgs/img.png)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:flowable="http://flowable.org/bpmn" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC" xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI" typeLanguage="http://www.w3.org/2001/XMLSchema" expressionLanguage="http://www.w3.org/1999/XPath" targetNamespace="http://www.flowable.org/processdef" exporter="Flowable Open Source Modeler" exporterVersion="6.7.2">
+    <process id="a1" name="1" isExecutable="true">
+        <startEvent id="startEvent1" flowable:formFieldValidation="true"></startEvent>
+        <exclusiveGateway id="sid-516CA2A3-F5BA-4AFF-8314-F87F2B9E2CF2" default="sid-6949581E-4B60-4263-9966-EF0C7D4D7D4F"></exclusiveGateway>
+        <userTask id="sid-6D86C326-54D1-4155-B564-9267C2E097BF" name="事业部审核" flowable:formFieldValidation="true"></userTask>
+        <sequenceFlow id="sid-5BFB5B2B-C9A8-42D2-9AB5-AD886D1E5235" sourceRef="sid-516CA2A3-F5BA-4AFF-8314-F87F2B9E2CF2" targetRef="sid-6D86C326-54D1-4155-B564-9267C2E097BF"></sequenceFlow>
+        <userTask id="sid-08E30960-3B2C-40D4-8B8D-34BBC7213F2F" name="财务审核" flowable:formFieldValidation="true"></userTask>
+        <endEvent id="sid-DB91A9BE-D1AE-4410-B502-86331F330066"></endEvent>
+        <exclusiveGateway id="sid-86533789-DD27-4186-BB4F-4F9526CD930C"></exclusiveGateway>
+        <sequenceFlow id="sid-531523D8-9C8A-4F07-8786-D9389A9E693B" sourceRef="sid-6D86C326-54D1-4155-B564-9267C2E097BF" targetRef="sid-86533789-DD27-4186-BB4F-4F9526CD930C"></sequenceFlow>
+        <sequenceFlow id="sid-3D02CE81-4BBE-4611-AE68-6CF23DB0BB22" sourceRef="sid-86533789-DD27-4186-BB4F-4F9526CD930C" targetRef="sid-DB91A9BE-D1AE-4410-B502-86331F330066"></sequenceFlow>
+        <userTask id="sid-9134DB2B-33BF-423A-B916-1065A12A7D34" name="部门主管审核" flowable:formFieldValidation="true"></userTask>
+        <sequenceFlow id="sid-C62405A5-DC20-4273-A550-D5477143908E" sourceRef="startEvent1" targetRef="sid-9134DB2B-33BF-423A-B916-1065A12A7D34"></sequenceFlow>
+        <sequenceFlow id="sid-7C7099A5-12BA-4E87-BE02-3A70788A2DE9" sourceRef="sid-9134DB2B-33BF-423A-B916-1065A12A7D34" targetRef="sid-516CA2A3-F5BA-4AFF-8314-F87F2B9E2CF2"></sequenceFlow>
+        <userTask id="sid-613723D4-E36F-4902-AE52-37F3CF6E75C9" name="董事会审核" flowable:formFieldValidation="true"></userTask>
+        <sequenceFlow id="sid-454E0650-77EE-4E00-AE5C-0A6CDFF8A975" sourceRef="sid-08E30960-3B2C-40D4-8B8D-34BBC7213F2F" targetRef="sid-613723D4-E36F-4902-AE52-37F3CF6E75C9"></sequenceFlow>
+        <sequenceFlow id="sid-3E71B6E4-5A4B-4066-B653-029CBD856D9D" sourceRef="sid-613723D4-E36F-4902-AE52-37F3CF6E75C9" targetRef="sid-86533789-DD27-4186-BB4F-4F9526CD930C"></sequenceFlow>
+        <sequenceFlow id="sid-6949581E-4B60-4263-9966-EF0C7D4D7D4F" sourceRef="sid-516CA2A3-F5BA-4AFF-8314-F87F2B9E2CF2" targetRef="sid-08E30960-3B2C-40D4-8B8D-34BBC7213F2F"></sequenceFlow>
+    </process>
+    <bpmndi:BPMNDiagram id="BPMNDiagram_a1">
+        <bpmndi:BPMNPlane bpmnElement="a1" id="BPMNPlane_a1">
+            <bpmndi:BPMNShape bpmnElement="startEvent1" id="BPMNShape_startEvent1">
+                <omgdc:Bounds height="30.0" width="30.0" x="120.0" y="193.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="sid-516CA2A3-F5BA-4AFF-8314-F87F2B9E2CF2" id="BPMNShape_sid-516CA2A3-F5BA-4AFF-8314-F87F2B9E2CF2">
+                <omgdc:Bounds height="40.0" width="40.0" x="370.0" y="188.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="sid-6D86C326-54D1-4155-B564-9267C2E097BF" id="BPMNShape_sid-6D86C326-54D1-4155-B564-9267C2E097BF">
+                <omgdc:Bounds height="80.0" width="100.0" x="450.0" y="60.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="sid-08E30960-3B2C-40D4-8B8D-34BBC7213F2F" id="BPMNShape_sid-08E30960-3B2C-40D4-8B8D-34BBC7213F2F">
+                <omgdc:Bounds height="80.0" width="100.0" x="450.0" y="285.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="sid-DB91A9BE-D1AE-4410-B502-86331F330066" id="BPMNShape_sid-DB91A9BE-D1AE-4410-B502-86331F330066">
+                <omgdc:Bounds height="28.0" width="28.0" x="810.5" y="204.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="sid-86533789-DD27-4186-BB4F-4F9526CD930C" id="BPMNShape_sid-86533789-DD27-4186-BB4F-4F9526CD930C">
+                <omgdc:Bounds height="40.0" width="40.0" x="720.0" y="198.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="sid-9134DB2B-33BF-423A-B916-1065A12A7D34" id="BPMNShape_sid-9134DB2B-33BF-423A-B916-1065A12A7D34">
+                <omgdc:Bounds height="80.0" width="100.0" x="210.0" y="168.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+
+            <bpmndi:BPMNShape bpmnElement="sid-613723D4-E36F-4902-AE52-37F3CF6E75C9" id="BPMNShape_sid-613723D4-E36F-4902-AE52-37F3CF6E75C9">
+                <omgdc:Bounds height="80.0" width="100.0" x="595.0" y="285.0"></omgdc:Bounds>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNEdge bpmnElement="sid-454E0650-77EE-4E00-AE5C-0A6CDFF8A975" id="BPMNEdge_sid-454E0650-77EE-4E00-AE5C-0A6CDFF8A975" flowable:sourceDockerX="50.0" flowable:sourceDockerY="40.0" flowable:targetDockerX="50.0" flowable:targetDockerY="40.0">
+                <omgdi:waypoint x="549.95" y="325.0"></omgdi:waypoint>
+                <omgdi:waypoint x="594.9999999999807" y="325.0"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="sid-3D02CE81-4BBE-4611-AE68-6CF23DB0BB22" id="BPMNEdge_sid-3D02CE81-4BBE-4611-AE68-6CF23DB0BB22" flowable:sourceDockerX="20.5" flowable:sourceDockerY="20.5" flowable:targetDockerX="14.0" flowable:targetDockerY="14.0">
+                <omgdi:waypoint x="759.5520035885168" y="218.38622754491018"></omgdi:waypoint>
+                <omgdi:waypoint x="810.5002402842656" y="218.08303445075305"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="sid-6949581E-4B60-4263-9966-EF0C7D4D7D4F" id="BPMNEdge_sid-6949581E-4B60-4263-9966-EF0C7D4D7D4F" flowable:sourceDockerX="20.5" flowable:sourceDockerY="20.5" flowable:targetDockerX="50.0" flowable:targetDockerY="40.0">
+                <omgdi:waypoint x="390.5" y="227.44187392795882"></omgdi:waypoint>
+                <omgdi:waypoint x="390.5" y="325.0"></omgdi:waypoint>
+                <omgdi:waypoint x="450.0" y="325.0"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="sid-531523D8-9C8A-4F07-8786-D9389A9E693B" id="BPMNEdge_sid-531523D8-9C8A-4F07-8786-D9389A9E693B" flowable:sourceDockerX="50.0" flowable:sourceDockerY="40.0" flowable:targetDockerX="20.0" flowable:targetDockerY="20.0">
+                <omgdi:waypoint x="549.95" y="100.0"></omgdi:waypoint>
+                <omgdi:waypoint x="740.0" y="100.0"></omgdi:waypoint>
+                <omgdi:waypoint x="740.0" y="198.0"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="sid-7C7099A5-12BA-4E87-BE02-3A70788A2DE9" id="BPMNEdge_sid-7C7099A5-12BA-4E87-BE02-3A70788A2DE9" flowable:sourceDockerX="50.0" flowable:sourceDockerY="40.0" flowable:targetDockerX="20.0" flowable:targetDockerY="20.0">
+                <omgdi:waypoint x="309.9499999999041" y="208.0"></omgdi:waypoint>
+                <omgdi:waypoint x="370.0" y="208.0"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement"sid-C62405A5-DC20-4273-A550-D5477143908E" id="BPMNEdge_sid-C62405A5-DC20-4273-A550-D5477143908E" flowable:sourceDockerX="15.0" flowable:sourceDockerY="15.0" flowable:targetDockerX="50.0" flowable:targetDockerY="40.0">
+                <omgdi:waypoint x="149.94999883049306" y="208.0"></omgdi:waypoint>
+                <omgdi:waypoint x="209.99999999995785" y="208.0"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="sid-5BFB5B2B-C9A8-42D2-9AB5-AD886D1E5235" id="BPMNEdge_sid-5BFB5B2B-C9A8-42D2-9AB5-AD886D1E5235" flowable:sourceDockerX="20.5" flowable:sourceDockerY="20.5" flowable:targetDockerX="50.0" flowable:targetDockerY="40.0">
+                <omgdi:waypoint x="390.5" y="188.5"></omgdi:waypoint>
+                <omgdi:waypoint x="390.5" y="100.0"></omgdi:waypoint>
+                <omgdi:waypoint x="450.0" y="100.0"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="sid-3E71B6E4-5A4B-4066-B653-029CBD856D9D" id="BPMNEdge_sid-3E71B6E4-5A4B-4066-B653-029CBD856D9D" flowable:sourceDockerX="50.0" flowable:sourceDockerY="40.0" flowable:targetDockerX="20.0" flowable:targetDockerY="20.0">
+                <omgdi:waypoint x="694.9499999999887" y="325.0"></omgdi:waypoint>
+                <omgdi:waypoint x="740.0" y="325.0"></omgdi:waypoint>
+                <omgdi:waypoint x="740.0" y="237.90928437792334"></omgdi:waypoint>
+            </bpmndi:BPMNEdge>
+        </bpmndi:BPMNPlane>
+    </bpmndi:BPMNDiagram>
+</definitions>
+```
+
+> 通过上面的 BPMN 协议的具体内容, 我们可以发现协议内容主要分为两大块, 一块是以`<process>`包裹, 它是主要的规则描述,
+> 另一块是以`<bpmndi:BPMNDiagram>`包裹, 它是规则可视化的元数据, 这部分一般我们无需关系, 但只要我们的业务涉及到流程配置的反显,
+> 它又比不可少.
+
+### 4.2 Process 节点内容简易描述
+
+> 通过上面的协议内容, 可以发现有以下节点, 我们对出现过的节点简单描述
+
+- process 代表是一个可以被引擎处理的流程
+- startEvent 开始事件节点(**这里的需要注意命名, Event 代表是事件, 也就是说一个流程实例的开始, 是基于事件的,截止 23 年, 在
+  Flowable 中开始事件分为 9 种, 我们只用了空启动事件**)
+  > - 空启动事件
+  > - 定时器事件
+  > - 信号启动事件
+  > - 消息启动事件
+  > - 异常启动事件
+  > - 注册开始事件
+  > - 开始变量监听事件
+  > - 升级开始事件
+  > - 条件启动事件
+- exclusiveGateway 排它网关(**控制流程如何流转, 是最常用的一个基础组件,只要涉及到条件流转,都需要用它,在 Flowable 中,网关也有
+  4 种, 我们只用了排它网关和并行网关**)
+  > - 排它网关
+  > - 并行网关
+  > - 事件网关
+  > - 包容网关
+- userTask 用户任务(**需要人为介入的节点,一般情况下只要人类不对该节点做动作,那么流程就永远卡在这里,不再执行**)
+- sequenceFlow 顺序流(**用于连接两个节点间的连线,很重要的组件,如果连线不正确,或者中断,会直接影响引擎的执行**)
+- endEvent 结束事件节点
+
+### 4.3 流程模型与流程定义
+
+> 以上仅仅是冰山一角, 大致了解了最初级的协议内容后, 同时我们也称上面的协议内容为**流程定义**, 流程定义是一种较为底层的元数据.
+>
+> 因为我们一般针对某个流程规则, 会时不时的修改和调整, 修改后如何保证使用方无感知, 但对于工作流来说又是可追溯的,
+> 所以需要再抽象一层来保存同一个流程的所有修改过程, 我们称这个抽象层为**流程模型**.
+> 也就是说, 一个流程模型是一个流程, 这个流程的的多次修改(多版本)都在这个模型下. 而使用方也就只用关心流程模型的唯一标识即可.
+>
+> 我们编辑好流程模型与流程定义后, 还需要对流程模型(定义)发布, 才能真正的被使用. 发布后, 这一次的流程定义将定型,不再允许改变当前版本的内容.
+> 如需修改规则, 则会产生新的版本.
+
+流程模型: 对应库表: act_re_model
+流程定义: 对应库表: act_re_procdef
+流程发布: 对应库表: act_re_deployment/act_ge_bytearray
+
+以上仅仅是冰山一角, 大致了解了最初级的协议内容后, 同时我们也称上面的协议内容为`流程定义`, 我们再看看如何运行它?
+
+## 5. 如何运行一个流程?
+
+> 在介绍上面的协议内容时, 说了我们只用了空启动事件, 那我们怎么启动呢? 虽然说它是事件, 但我们实际发起流程并不是直接操作的事件,
+> 而是操作引擎为我们提供API.
+> `org.flowable.engine.RuntimeService#ProcessInstanceBuilder#start()`
+
+### 5.1 简单了解 Flowable 引擎常用的 API (门面模式)
+
+> API 的相关作用,都在对应类有注解, 自行查阅
+
+- org.flowable.engine.RuntimeService 运行时相关
+- org.flowable.engine.RepositoryService 元数据相关
+- org.flowable.engine.HistoryService 历史数据相关
+- org.flowable.engine.TaskService 审批任务相关
+
+### 5.2 运行(前/中)的困惑?
+
+> 有没有发现一个问题? 我们从头到现在几乎没有说审批人相关问题或配置, 包括 BPMN 协议内容中也没有审批人的信息. 能发起成功吗?
+>
+> 首先回答: 能正常发起,并且流程也能处理运转. 只是像之前说的没有人为操作, 流程会永远的停止在第一个审批节点,
+> 然后这前提是规则里面至少有一个 userTask.
+> 如果 BPMN 规则里面,只有 startEvent 直接连接的 endEvent, 那么发起即结束.
+
+## 6. 流程引擎内部是如何运行的?
+
+> Flowable 分为多个引擎, 包括 BPMN 引擎/CMMN 引擎/DMN 引擎/Form 引擎/IDM 引擎, 而我们主要关注 BPMN 引擎即可.
+> 所有的引擎的采用的设计模式是一致的, 统一的采用了命令模式. 引擎内部的每一步动作都是依靠一个Agenda(待办)
+> 来临时存储后续动作的"命令".
+>
+> 所以我们研究引擎需要研究各种命令(XXXCmd). 这些命令是进入引擎内部的入口, 可以通过查看
+> org.flowable.common.engine.impl.interceptor.Command 的继承关系看到具体的命令. 当然引擎还有更多的逻辑,
+> 真正处理各种类型节点的是对应的行为(XXXBehavior), 可以通过查看 `org.flowable.engine.impl.delegate.ActivityBehavior`
+> 的继承关系看到具体的行为.
+>
+> 例如: 想看发起过程需要研究: StartProcessInstanceCmd#execute
+
+## 6. 如何与外部交互?
+
+> 工作流引擎作为服务端, 与外部系统交互分为两类, 一类是操作引擎, 一般提供 API 入口, 由外部推动. 另一类是引擎内部状态通知给使用方,
+> 是由服务端广播出去.
+
+### 6.1 外部操作引擎
+
+> 本工程提供两种使用接入方式, 一种是 jar 包集成, 可参考[这个说明](workflow-engine-core/src/main/resources/readme.md),
+> 另一种是 Feign API 集成, 主要参考`workflow-engine-server`module
+> 中包路径为 `src/main/java/cn/axzo/workflow/server/controller/web` 下的文件.
+
+### 6.2 引擎内部事件广播
+
+> 引擎内部的事件类型非常多, org.flowable.common.engine.api.delegate.event.FlowableEngineEventType 通过这个类可以看到引擎会触发的事件类型.
+>
+> 本工程根据公司需要, 将引擎部分事件广播给使用方, 其他事件则不广播. 同时这些事件也被用于本工程的一些场景的消费.
+
+**广播的事件接口**
+
+- cn.axzo.workflow.core.listener.BpmActivityEventListener
+- cn.axzo.workflow.core.listener.BpmTaskEventListener
+- cn.axzo.workflow.core.listener.BpmProcessEventListener
+
+**以下总结下哪些接口触发哪些事件**
+
+- cn.axzo.workflow.client.feign.bpmn.ProcessInstanceApi.createProcessInstance
+
+> 发起流程 MQ 触发规则:
+> 1. 当前流程实例会依次触发 process-instance-created 和 process-instance-started 事件
+> 2. 第一个审批任务会依次触发 process-task-assigned 和 process-task-created 事件
+
+- cn.axzo.workflow.client.feign.bpmn.ProcessInstanceApi.cancelProcessInstance
+
+> 取消流程 MQ 触发规则:
+> 1. 当前流程实例中现存的任务会依次触发 process-task-deleted 事件
+> 2. 当前流程实例会触发 process-instance-cancelled 事件
+
+- cn.axzo.workflow.client.feign.bpmn.ProcessTaskApi.approveTask
+
+> 任务节点通过审批 MQ 触发规则:
+> 1. 当前审批任务会依次触发 process-task-completed 和 process-task-deleted 事件(如果有下一级审批,则会触发第 2.1 点中的事件,
+     如果当前审核任务最后一级审批,则会触发第 2.2 点中的事件)
+     > 2.1. 下一级审批任务会依次触发 process-task-assigned 和 process-task-created 事件
+     > 2.2. 流程实例正常结束会触发 process-instance-completed 事件
+
+- cn.axzo.workflow.client.feign.bpmn.ProcessTaskApi.rejectTask
+
+> MQ 触发规则:
+> 1. 当前审批任务会触发 process-task-deleted 事件
+> 2. 当前流程实例会触发 process-instance-rejected 事件
+
+## 99.建设状态(过时)
+
+### 99.1 已完成:
 
 1. 全新搭建工作流微服务
 2. 工作流模型中 JSON 格式的协议支持
@@ -55,7 +313,7 @@
 5. 重构工作流服务 Process 引擎相关接口,并按照框架简单接入和测试内置表单
 6. 重构业务分类/流程状态/审批状态运行时以及历史数据的处理方式
 
-待办项:
+### 99.2 待办项:
 
 1. BPMN 协议兼容(XML/JSON已支持)
 2. 工作流内部接入组织架构
@@ -63,14 +321,3 @@
 4. 审批模型审批人配置管理与持久化
 5. 审批模型表单能力的接入和调整
 5. Flowable Event MQ 事件生产与消费
-
-## 一些暂无法归类的信息
-
-1. BPMN 协议中,`UserTask`可以增加自定义的监听, 监听器类型分为两大类: 执行监听器(`ExecutionListener`)
-   和任务监听器(`TaskListener`), 其中执行监听较为抽象, 在实例运行中,每个节点都有一个 ExecutionEntity, 目前这个 Execution
-   概念还比较模糊. 而任务监听器是针对 UserTask 节点存在的.
-
-> `ExecutionListener` event 分为: start/end/take
-> `TaskListener` event 分为: create/assignment/complete/delete
-
-2.