wsmandClaude Opus 4.7
d5a1d9842d
涵盖 Flowable 6.8.0 之上的自定义元数据层设计、核心流程全链路、 数据库表全景、关键文件速查。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
21 KiB
21 KiB
流程引擎架构分析
基于 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，并非快照。代码注释标注了已知问题：
// 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 中通过表达式回调：
<sequenceFlow sourceRef="Gateway_01" targetRef="Task_02">
<conditionExpression>${xiSpeakFlow.getNeedSdwApproval(jsonData)}</conditionExpression>
</sequenceFlow>
业务监听器在 BPMN 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/ 反馈流程业务监听器
七、关键设计决策
- 双层定义：
ext_act_process存 BPMN XML + 简流 JSON，同时服务可视化设计器和低代码平台 - 实时 vs 快照：节点配置分
ext_act_process_node（实时）和ext_act_process_node_deploy（快照），当前运行时实际读取实时表 - 双写审批记录：
ExtActBpmLog（旧表）+TaskApprovalOpinion（新表），旧表写入成功后尽力双写新表，新表失败不影响主流程 - 门面模式：
BpmBaseExtApiImpl是外部系统调用流程能力的唯一入口，隔离了内部实现细节 - Java Bean 表达式：XiSpeak 流程通过 Spring Bean 方法注入业务逻辑到 BPMN 条件表达式中，实现比 UEL 表达式更复杂的动态计算