# 流程引擎架构分析

基于 Flowable 6.8.0，Jeecg 在之上封装了自定义的流程元数据管理层，Flovable 仅作为 BPMN 执行内核使用。

---

## 整体分层

```
┌──────────────────────────────────────────────────┐
│                 前端 (Vue 3)                       │
│  流程设计器 │ 待办任务 │ 审批表单 │ 流程列表        │
└──────────────────┬───────────────────────────────┘
                   │ REST API
┌──────────────────┴───────────────────────────────┐
│             ActTaskController                     │
│  /act/task/list  /act/task/processComplete ...    │
│  /act/process/deploy  /act/process/list ...       │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────┴───────────────────────────────┐
│              业务门面层 (Facade)                   │
│  BpmBaseExtApiImpl  —  对外统一入口               │
│  ExtActProcessServiceImpl  —  核心编排 (1493行)   │
└──────────────────┬───────────────────────────────┘
                   │
      ┌────────────┼────────────┐
      ▼            ▼            ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ ext_act_ │ │ Flowable │ │ 业务表单  │
│  元数据层 │ │  执行引擎 │ │  数据层   │
└──────────┘ └──────────┘ └──────────┘
```

---

## 一、自定义元数据层（ext_act_* 14 张表）

### 1.1 流程定义 — ext_act_process

**Entity:** `ExtActProcess.java`

双格式存储 BPMN 定义，同时支持可视化设计器和"简流"低代码 JSON 格式：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | String | 主键 |
| `processKey` | String | 流程标识，跨版本唯一 |
| `processName` | String | 流程名称 |
| `processXml` | byte[] | 标准 BPMN 2.0 XML |
| `processJson` | String | "简流"低代码设计器 JSON |
| `startType` | Integer | 触发方式：手动/表事件/定时器/信号/按钮 |
| `processStatus` | Integer | 0=未部署, 1=已部署 |
| `deploymentId` | String | 关联 Flowable `act_re_deployment.ID_` |
| `processDeployTime` | Date | 最近一次部署时间 |
| `categoryId` | String | 流程分类 |
| `updateCount` | Integer | @Version 乐观锁 |

**版本管理：** `ext_act_process` 不维护版本号。版本由 Flowable 原生管理——每次 `deployProcess()` 在 `act_re_procdef` 中自动递增 `VERSION_`。历史版本仅在 Flowable 引擎表中保留。

### 1.2 表单绑定 — ext_act_process_form

**Entity:** `ExtActProcessForm.java`

流程与业务表单的映射关系，运行时启动流程时以此表为依据：

| 字段 | 说明 |
|------|------|
| `relationCode` | 流程编码（如 `bg_xi_speak_001`），作为流程启动的唯一标识 |
| `processId` | 关联 `ext_act_process.id` |
| `formType` | 1=Online在线表单, 2=设计器表单, 3=自定义开发 |
| `formTableName` | 业务数据表名或设计器表名 |
| `flowStatusCol` | 业务表中存储流程状态的字段名 |
| `titleExp` | 标题表达式，如 `{name}的请假申请` |
| `triggerAction` | 自动触发时机：add/update/delete |
| `startSignalName` | 信号启动名称模式 |

### 1.3 节点配置（三层结构）

#### ext_act_process_node — 实时配置

运行时直接读取此表。每个节点可配置：

| 配置项 | 字段 | 说明 |
|--------|------|------|
| 表单可编辑 | `formEditStatus` | 审批时表单是否可修改 |
| 抄送 | `ccStatus` | 是否允许抄送 |
| 自选下一节点 | `selnextUserStatus` | 是否允许选择下一审批人 |
| 消息通知 | `msgStatus` | 是否发送通知 |
| 转办 | `transferStatus` | 是否允许转办 |
| 加签 | `addSignStatus` | 是否允许加签 |
| 驳回 | `rejectStatus` | 是否允许驳回 |
| 计数器加签 | `allowCounterSignAddUser` | 会签中是否允许添加会签人 |
| 扩展配置 | `nodeConfigJson` | 邮件/钉钉/系统通知的详细配置 |

#### ext_act_process_node_deploy — 部署快照

`deployProcess()` 时从 `ext_act_process_node` 复制，按 `deploymentId` 隔离。设计上是为了版本锁定，但**当前代码实际运行时读取的是实时 `ext_act_process_node`**，并非快照。代码注释标注了已知问题：

```java
// ActTaskController.java line 322
// TODO bug, 这里读取的不是发布后的配置
```

#### ext_act_process_node_auth — 字段权限

按节点+表单字段维度控制：可见/禁用/必填。支持 Online 表单（formType=1）和设计器表单（formType=2）。

| 字段 | 说明 |
|------|------|
| `ruleType` | 1=显示, 2=禁用 |
| `required` | 是否必填 |
| `desformComKey` | 设计器表单控件 key |

### 1.4 运行时关联 — ext_act_flow_data

**Entity:** `ExtActFlowData.java`

业务记录与 Flowable 流程实例的桥接表，是运行时状态的核心：

```
formDataId + processKey + relationCode  →  processInstId
```

生命周期：

```
草稿 (bpmStatus="1")
  → 创建记录，processInstId = NULL

运行中 (bpmStatus="2")
  → runtimeService.startProcessInstanceByKey() 后写入 processInstId
  → 同步回写业务表 flowStatusCol

完成 (bpmStatus="3")
  → ProcessEndListener 正常结束时更新

作废 (bpmStatus="4")
  → 流程被作废时更新

撤回 (bpmStatus="callbackProcess")
  → 删除 ext_act_flow_data 记录，业务表状态重置
```

### 1.5 其他辅助表

| 表名 | Entity | 用途 |
|------|--------|------|
| `ext_act_bpm_log` | `ExtActBpmLog` | 审批操作日志，每个节点审批时写入一条 |
| `ext_act_bpm_file` | `ExtActBpmFile` | 审批附件，关联 `bpm_log_id` |
| `ext_act_task_cc` | `ExtActTaskCc` | 任务抄送记录 |
| `ext_act_task_notification` | `ExtActTaskNotification` | 催办/通知记录 |
| `ext_act_listener` | `ExtActListener` | 监听器注册表，供设计器选配 |
| `ext_act_expression` | `ExtActExpression` | 表达式库，候选人公式等 |
| `ext_act_design_flow_data` | `ExtActDesignFlowData` | 设计器表单与流程的运行时关联 |

---

## 二、核心流程：从设计到执行

### 2.1 设计阶段

```
┌──────────────┐     saveProcess()      ┌───────────────────────┐
│ 流程设计器     │ ─────────────────────→ │ ext_act_process        │
│ (前端Vue)     │                       │  .processXml (BPMN)    │
└──────────────┘                       │  .processJson (简流)   │
                                       └───────────┬───────────┘
                                                   │ BpmnXMLConverter
                                                   │ 解析 UserTask 节点
                                                   ▼
                                       ┌───────────────────────┐
                                       │ ext_act_process_node   │
                                       │  自动创建 + 默认配置    │
                                       └───────────────────────┘

             deployProcess()
┌──────────────────────────────────────────────────────────────┐
│ 1. repositoryService.createDeployment(processXml)             │
│    → act_re_deployment + act_re_procdef + act_ge_bytearray    │
│ 2. 快照 ext_act_process_node → ext_act_process_node_deploy    │
│ 3. 更新 processStatus = 1, processDeployTime                  │
└──────────────────────────────────────────────────────────────┘
```

### 2.2 启动阶段

```
BpmBaseExtApiImpl.startMutilProcess(flowCode, formDataId, formUrl, username, jsonData)
  │
  ├─ 1. 查 ext_act_process_form WHERE relationCode = flowCode
  ├─ 2. 查业务数据 (SQL / MongoDB)
  ├─ 3. 组装流程变量:
  │      BPM_DATA_ID          = formDataId
  │      BPM_FORM_KEY         = flowCode
  │      BPM_FORM_CONTENT_URL = formUrl
  │      BPM_BIZ_TITLE        = 标题表达式解析结果
  │      BPM_STATUS           = "2" (处理中)
  │      BPM_FORM_TYPE        = 1/2/3
  │      json_data            = 业务表单数据 JSON
  │
  ├─ 4. identityService.setAuthenticatedUserId(initiator)
  ├─ 5. runtimeService.startProcessInstanceByKey(processKey, businessKey, variables)
  │      → 返回 processInstanceId
  │
  ├─ 6. 创建/更新 ext_act_flow_data (businessKey → processInstanceId 映射)
  └─ 7. 回写业务表 flowStatusCol = "2"
```

### 2.3 审批阶段

```
┌─────────────────────────────────────────────────────────────┐
│ GET /act/task/list                                          │
│   → ActivitiServiceImpl.findPriTodoTasks()                  │
│   返回当前用户的待办任务列表                                    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ GET /act/task/getProcessTaskTransInfo?taskId=xxx            │
│   → 查询 ext_act_process_node（实时配置）                     │
│   返回:                                                      │
│     formEditStatus     — 表单是否可编辑                       │
│     ccStatus           — 是否允许抄送                         │
│     selnextUserStatus  — 是否允许自选下一节点                  │
│     rejectStatus       — 是否允许驳回                         │
│     transferStatus     — 是否允许转办                         │
│     addSignStatus      — 是否允许加签                         │
│     bpmLogList         — 审批历史时间线                       │
│     transitionList     — 可选的下一步操作                     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ POST /act/task/processComplete                              │
│   → ExtActTaskCcServiceImpl.processComplete()               │
│                                                              │
│   1. 设置 BPM_STATUS = "2"                                   │
│   2. 写入审批结果变量 approve_result_{taskDefKey}             │
│   3. 判断会签 → 设置候选人列表变量                             │
│   4. 路由分发:                                                │
│      · model="1" 单分支 → handTaskComplete()                 │
│        └ taskService.complete(taskId, variables)             │
│      · model="2" 多分支 → SuperTaskService.goProcessTaskNode()│
│        └ runtimeService.createChangeActivityStateBuilder()   │
│          .moveActivityIdTo(nextNode)                         │
│      · 驳回 → backToStepTask()                               │
│        └ .moveActivityIdTo(历史节点)                          │
│   5. 处理加签/委派子任务                                       │
│   6. saveTaskHandBpmLog() → ext_act_bpm_log                  │
│   7. TaskUpdateFormDataListener 刷新流程变量                  │
└─────────────────────────────────────────────────────────────┘
```

### 2.4 结束阶段

```
流程到达结束事件
  → ProcessEndListener.notify(execution)
     │
     ├─ BPM_STATUS = "callbackProcess"
     │    → delete ext_act_flow_data
     │    → 业务表状态重置为 "1"
     │
     ├─ BPM_STATUS = "invalidProcess"
     │    → ext_act_flow_data.bpmStatus = "4"
     │    → 业务表 flowStatusCol = "4"
     │
     └─ 其他（正常完成）
          → ext_act_flow_data.bpmStatus = "3"
          → 业务表 flowStatusCol = "3"
```

---

## 三、两种流程定义方式

| 维度 | DB 定义流程 | Java 定义流程 |
|------|------------|-------------|
| **BPMN 来源** | 可视化设计器 → `ext_act_process.processXml` | 手工编写 BPMN XML |
| **监听器** | XML 中注册全限定类名 | `@Component` Spring Bean |
| **表达式** | 直接写在 XML 条件中 | Java 方法：`${xiSpeakFlow.getNeedSdwApproval()}` |
| **节点配置** | 前端设计器编辑 → `ext_act_process_node` | 同左或手动插入 |
| **示例** | 通用审批流程 | `XiSpeakFlow`、`XiSpeakFeedbackFlow` |
| **部署方式** | `deployProcess()` | 同样 `deployProcess()` |
| **代码位置** | — | `jeecg-module-flow` |

### XiSpeak 示例

`XiSpeakFlow.java` 注册为 Spring Bean `"xiSpeakFlow"`，在 BPMN XML 中通过表达式回调：

```xml
<sequenceFlow sourceRef="Gateway_01" targetRef="Task_02">
  <conditionExpression>${xiSpeakFlow.getNeedSdwApproval(jsonData)}</conditionExpression>
</sequenceFlow>
```

业务监听器在 BPMN XML 中以全限定类名注册：

```xml
<flowable:taskListener event="complete"
  class="org.jeecg.xispeak.listener.AfterImplDeptLeaderApproveListener"/>
```

---

## 四、特殊流程能力

| 能力 | 实现方式 | 关键类 |
|------|---------|--------|
| **会签** | Flowable `multiInstanceLoopCharacteristics`，运行时 XML 解析判断 | `SuperTaskService.checkUserTaskIsHuiQian()` |
| **加签** | Flowable `Command<Void>` 动态修改 BPMN 模型，插入新 UserTask | `AfterSignUserTaskCmd` |
| **驳回** | `runtimeService.createChangeActivityStateBuilder().moveActivityIdTo(历史节点)` | `ExtActTaskCcServiceImpl.backToStepTask()` |
| **转办** | `taskService.setAssignee(taskId, newUserId)` | `ActTaskController.complaint()` |
| **委派** | `taskService.delegateTask(taskId, delegateUser)` | `ActTaskController.delegate()` |
| **撤回** | 设 `BPM_STATUS = "callbackProcess"` → `actProcessService.stopProcessInstanceById()` | `ActTaskController.callbackProcess()` |
| **任务变量刷新** | 每个 UserTask 创建时从业务库拉最新表单数据注入流程变量 | `TaskUpdateFormDataListener` |
| **信号启动** | 低代码"简流"模式，通过信号事件触发子流程 | `SignalProcessStartListener` |

---

## 五、数据库表全景

### Flowable 引擎表（47张）

| 类别 | 前缀 | 数量 | 说明 |
|------|------|------|------|
| 运行时 | `act_ru_*` | 13 | 运行中的流程实例、任务、变量 |
| 历史 | `act_hi_*` | 10 | 已完成的流程实例历史 |
| 仓库 | `act_re_*` | 3 | 流程定义、部署、模型 |
| 通用 | `act_ge_*` | 2 | 字节数组、属性 |
| 身份 | `act_id_*` | 8 | 用户、组、权限 |
| 事件 | `act_evt_*` / `flw_*` | 11 | 事件日志、事件定义、批量 |

### 自定义表（14张）

| 类别 | 表名 | 用途 |
|------|------|------|
| 流程定义 | `ext_act_process` | 流程定义（BPMN XML + 简流 JSON） |
| 表单绑定 | `ext_act_process_form` | 流程与业务表单映射 |
| 节点配置 | `ext_act_process_node` | 节点实时配置 |
| 节点快照 | `ext_act_process_node_deploy` | 部署时节点配置快照 |
| 字段权限 | `ext_act_process_node_auth` | 节点字段级权限 |
| 运行时关联 | `ext_act_flow_data` | 业务数据 ↔ 流程实例 |
| 设计器运行时 | `ext_act_design_flow_data` | 设计器表单 ↔ 流程实例 |
| 审批日志 | `ext_act_bpm_log` | 审批操作记录 |
| 审批附件 | `ext_act_bpm_file` | 审批附件 |
| 抄送 | `ext_act_task_cc` | 任务抄送 |
| 催办通知 | `ext_act_task_notification` | 催办记录 |
| 监听器 | `ext_act_listener` | 监听器注册表 |
| 表达式 | `ext_act_expression` | 表达式库 |

### 业务表（与流程绑定）

| 表名 | 模块 | 说明 |
|------|------|------|
| `task_task` | tasktask | 事项任务计划表，核心督办任务记录 |
| `bg_xi_speak` | xispeak | 习总书记重要讲话指示批示 |
| `bg_xi_speak_feedback` | xispeak | 讲话指示批示反馈 |
| `task_approval_opinion` | taskapprovalopinion | 审批意见快照 |
| `dj_inspect_improve` | inspectimprove | 巡视整改台账 |

---

## 六、关键文件速查

```
jeecg-boot-platform/jeecg-boot-module-bpm-flowable/src/main/java/org/jeecg/modules/
├── extbpm/process/
│   ├── entity/
│   │   ├── ExtActProcess.java              ext_act_process 流程定义
│   │   ├── ExtActProcessForm.java          ext_act_process_form 表单绑定
│   │   ├── ExtActProcessNode.java          ext_act_process_node 节点实时配置
│   │   ├── ExtActProcessNodeDeployment.java ext_act_process_node_deploy 部署快照
│   │   ├── ExtActProcessNodePermission.java ext_act_process_node_auth 字段权限
│   │   ├── ExtActFlowData.java             ext_act_flow_data 运行时关联
│   │   ├── ExtActBpmLog.java               ext_act_bpm_log 审批日志
│   │   ├── ExtActBpmFile.java              ext_act_bpm_file 审批附件
│   │   ├── ExtActTaskCc.java               ext_act_task_cc 抄送
│   │   └── ExtActListener.java             ext_act_listener 监听器注册
│   ├── service/impl/
│   │   ├── ExtActProcessServiceImpl.java   ★ 核心编排服务 (1493行)
│   │   ├── ExtActTaskCcServiceImpl.java    审批完成+路由逻辑
│   │   ├── ExtActBpmLogServiceImpl.java    审批日志双写（旧表+新意见表）
│   │   └── BpmBaseExtApiImpl.java          对外门面 Facade
│   ├── listener/execution/
│   │   ├── ProcessEndListener.java         流程结束状态同步
│   │   ├── TaskUpdateFormDataListener.java 任务创建时刷新表单变量
│   │   └── SignalProcessStartListener.java 简流信号启动
│   └── common/
│       └── WorkFlowGlobals.java            流程常量定义
├── bpm/
│   ├── controller/
│   │   ├── ActTaskController.java          任务操作全部REST端点 (1633行)
│   │   └── ActProcessInstanceController.java 流程实例管理端点
│   ├── service/impl/
│   │   ├── ActivitiServiceImpl.java        任务查询+多实例+加签
│   │   ├── ActProcessService.java          Flowable原生部署/激活/挂起
│   │   └── SuperTaskService.java           节点跳跃+会签判断+转办
│   └── cmd/
│       └── AfterSignUserTaskCmd.java       动态加签 Command
└── taskapprovalopinion/
    ├── entity/TaskApprovalOpinion.java      task_approval_opinion 审批意见快照
    └── service/impl/                        CRUD 实现

jeecg-boot-module/jeecg-module-flow/src/main/java/org/jeecg/
├── xispeak/
│   ├── XiSpeakFlow.java                    表达 Bean ($xiSpeakFlow)
│   ├── XiSpeakConfig.java                  YAML 配置
│   └── listener/                           7个业务监听器
└── xispeakfb/
    ├── XiSpeakFeedbackFlow.java            反馈流程表达 Bean
    └── listener/                           反馈流程业务监听器
```

---

## 七、关键设计决策

1. **双层定义**：`ext_act_process` 存 BPMN XML + 简流 JSON，同时服务可视化设计器和低代码平台
2. **实时 vs 快照**：节点配置分 `ext_act_process_node`（实时）和 `ext_act_process_node_deploy`（快照），当前运行时实际读取实时表
3. **双写审批记录**：`ExtActBpmLog`（旧表）+ `TaskApprovalOpinion`（新表），旧表写入成功后尽力双写新表，新表失败不影响主流程
4. **门面模式**：`BpmBaseExtApiImpl` 是外部系统调用流程能力的唯一入口，隔离了内部实现细节
5. **Java Bean 表达式**：XiSpeak 流程通过 Spring Bean 方法注入业务逻辑到 BPMN 条件表达式中，实现比 UEL 表达式更复杂的动态计算