流程实例表

引用文件

本文引用的文件

简介

本文件围绕工作流模块中的流程实例表(bpm_process_instance)进行系统化梳理，覆盖以下主题：

生命周期管理：实例ID、流程定义ID、发起人、开始时间、结束时间等核心字段
状态管理：status 字段的取值、含义与流转
业务绑定：流程实例与业务表单的关联机制
流转控制与撤销：allow_cancel_running_process 的作用与业务约束
状态转换图与典型业务场景数据流转示例

项目结构

工作流模块采用分层架构，涉及 API、Biz、DAO、枚举、事件与 Flowable 集成等层次。与流程实例直接相关的结构包括：

数据表：bpm_process_instance（在 SQL 中定义）、bpm_process_instance_copy（抄送表）
枚举：BpmProcessInstanceStatusEnum（状态枚举）
服务：BpmProcessInstanceServiceImpl（流程实例查询、状态事件发布等）
监听器：BpmProcessInstanceEventListener（监听 Flowable 实例事件并更新状态）
VO/DTO/API：BpmProcessInstance*（响应、请求、API 接口）
事件：BpmProcessInstanceStatusEvent（状态变更事件）

Mermaid Diagram Code:

graph TB
subgraph "API 层"
API["BpmProcessInstanceApi<br/>BpmProcessInstanceApiImpl"]
end
subgraph "业务层"
Svc["BpmProcessInstanceServiceImpl"]
Listener["BpmProcessInstanceEventListener"]
Publisher["BpmProcessInstanceEventPublisher"]
end
subgraph "领域与枚举"
Enum["BpmProcessInstanceStatusEnum"]
VO["BpmProcessInstanceRespVO<br/>BpmProcessInstanceBpmnModelViewRespVO"]
DTO["BpmProcessInstanceQueryReqDTO<br/>BpmProcessInstanceCreateReqDTO<br/>BpmProcessInstanceDelReqDTO"]
end
subgraph "持久层"
DAO["BpmProcessDefinitionInfoDO<br/>BpmProcessInstanceCopyDO<br/>BpmInstanceStatusMessageDO"]
end
subgraph "数据库"
TBL1["bpm_process_instance"]
TBL2["bpm_process_instance_copy"]
end
API --> Svc
Svc --> Enum
Svc --> Listener
Listener --> Publisher
Svc --> DAO
DAO --> TBL1
DAO --> TBL2
VO --> Svc
DTO --> API

图表来源

章节来源

核心组件

流程实例状态枚举：定义了“未开始、审批中、审批通过、审批不通过、已取消”等状态及判断逻辑
流程实例服务：负责查询、状态事件发布、与 Flowable 的交互
Flowable 监听器：监听流程实例创建、完成、取消事件，驱动状态更新
VO/DTO/API：封装对外接口与内部处理的数据结构
数据表：bpm_process_instance 及 bpm_process_instance_copy

章节来源

架构总览

流程实例生命周期由 Flowable 引擎驱动，系统通过监听器捕获关键事件并更新状态；同时，系统提供查询、状态事件发布与业务绑定能力。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "BpmProcessInstanceApiImpl"
participant Svc as "BpmProcessInstanceServiceImpl"
participant Engine as "Flowable 引擎"
participant Lsn as "BpmProcessInstanceEventListener"
participant Pub as "BpmProcessInstanceEventPublisher"
Client->>API : 发起流程实例
API->>Svc : 创建流程实例
Svc->>Engine : 启动流程实例
Engine-->>Svc : 返回实例ID
Svc-->>API : 返回实例ID
API-->>Client : 成功响应
Engine-->>Lsn : 触发事件(PROCESS_CREATED/COMPLETED/CANCELLED)
Lsn->>Svc : 更新状态
Svc->>Pub : 发布状态事件

图表来源

详细组件分析

数据表结构与字段说明

bpm_process_instance（核心表，包含流程实例关键字段）
bpm_process_instance_copy（抄送表，记录抄送信息）

字段要点（基于 SQL 定义与业务语义归纳）：

实例ID：流程实例唯一标识
流程定义ID：关联流程定义
发起人：startUserId
开始时间：createTime
结束时间：endTIme（历史实例）
状态：status（枚举映射）
业务键：businessKey（用于业务绑定）
表单变量：processVariables（流程变量，含表单字段）

章节来源

bpm.sql

流程实例状态与业务含义

状态枚举定义如下：

未开始：NOT_START
审批中：RUNNING
审批通过：APPROVE
审批不通过：REJECT
已取消：CANCEL

状态判断辅助方法：

isRejectStatus：判断是否为“审批不通过”
isProcessEndStatus：判断是否为结束态（通过/不通过/取消）
getByStatus：按状态值获取枚举

Mermaid Diagram Code:

stateDiagram-v2
[*] --> 未开始
未开始 --> 审批中 : "启动流程"
审批中 --> 审批通过 : "审批通过"
审批中 --> 审批不通过 : "审批不通过"
审批中 --> 已取消 : "撤销流程"
审批通过 --> [*]
审批不通过 --> [*]
已取消 --> [*]

图表来源

BpmProcessInstanceStatusEnum.java

章节来源

BpmProcessInstanceStatusEnum.java

流程实例与业务表单的关联机制

业务绑定：通过 businessKey 将流程实例与具体业务记录关联
表单变量：processVariables 存放表单字段与业务数据
流程定义信息：BpmProcessDefinitionInfoDO 提供表单类型、表单配置等，决定表单展示与校验
抄送机制：bpm_process_instance_copy 记录抄送人与活动节点信息

章节来源

流转控制与撤销机制

撤销开关：allow_cancel_running_process（流程定义信息表字段），控制是否允许撤销“审批中”的申请
业务约束：当 allow_cancel_running_process 为真时，系统允许撤销；否则不允许
事件驱动：通过 Flowable 事件监听器捕获取消事件并更新状态

章节来源

查询与数据转换

查询接口：支持按实例ID、流程定义Key、业务Key、状态等条件组合查询
数据转换：BpmProcessInstanceConvert 负责将运行时/历史实例转换为对外 VO，并注入状态、表单变量、流程定义与发起人信息

章节来源

API 与控制器

API：对外暴露创建、查询、撤销等能力
控制器：接收前端请求，调用服务层执行业务逻辑

章节来源

依赖关系分析

服务层依赖 Flowable 引擎与历史服务，以查询运行中/历史实例
监听器依赖 Flowable 事件类型，驱动状态更新
事件发布器负责将状态变更事件广播给订阅者
枚举与 VO/DTO/API 形成稳定的对外契约

Mermaid Diagram Code:

classDiagram
class BpmProcessInstanceServiceImpl {
+getProcessInstance(id)
+getHistoricProcessInstance(id)
+getProcessInstance(reqDTO)
+buildProcessInstanceStatusEvent(...)
}
class BpmProcessInstanceEventListener {
+PROCESS_INSTANCE_EVENTS
+onEvent(event)
}
class BpmProcessInstanceEventPublisher {
+publish(event)
}
class BpmProcessInstanceStatusEnum {
+NOT_START
+RUNNING
+APPROVE
+REJECT
+CANCEL
+isRejectStatus(status)
+isProcessEndStatus(status)
+getByStatus(status)
}
class BpmProcessInstanceRespVO
class BpmProcessInstanceBpmnModelViewRespVO
class BpmProcessDefinitionInfoDO
class BpmProcessInstanceCopyDO
BpmProcessInstanceServiceImpl --> BpmProcessInstanceEventListener : "事件回调"
BpmProcessInstanceServiceImpl --> BpmProcessInstanceEventPublisher : "发布事件"
BpmProcessInstanceServiceImpl --> BpmProcessInstanceStatusEnum : "状态判断"
BpmProcessInstanceServiceImpl --> BpmProcessInstanceRespVO : "返回"
BpmProcessInstanceServiceImpl --> BpmProcessInstanceBpmnModelViewRespVO : "返回"
BpmProcessInstanceServiceImpl --> BpmProcessDefinitionInfoDO : "关联"
BpmProcessInstanceServiceImpl --> BpmProcessInstanceCopyDO : "关联"

图表来源

性能考虑

查询优化：对按 businessKey、processDefinitionKey、status 的组合查询需确保索引覆盖
事件处理：监听器与事件发布应避免阻塞主线程，必要时异步化
历史数据：历史实例查询建议限制范围与分页，避免全量扫描

故障排查指南

状态异常：检查 Flowable 事件监听器是否正确触发，确认状态枚举映射
业务绑定问题：核对 businessKey 是否一致，表单变量是否正确写入
撤销失败：确认流程定义 allow_cancel_running_process 配置与业务规则

章节来源

结论

流程实例表承载了工作流的核心运行数据，配合状态枚举、事件监听与查询服务，实现了从启动、审批到结束或撤销的完整生命周期管理。通过 allow_cancel_running_process 与 businessKey 绑定，系统在灵活性与可控性之间取得平衡，满足多样化的业务审批需求。

附录

典型业务场景与数据流转示例

请假审批：业务表单 bpm_oa_leave 与流程实例通过 process_instance_id 关联；流程完成后，状态从“审批中”变为“审批通过”或“审批不通过”，并发送短信通知
抄送流程：bpm_process_instance_copy 记录抄送人与活动节点，便于后续审计与跟踪

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

数据表结构与字段说明​

流程实例状态与业务含义​

流程实例与业务表单的关联机制​

流转控制与撤销机制​

查询与数据转换​

API 与控制器​

依赖关系分析​

性能考虑​

故障排查指南​

结论​

附录​

典型业务场景与数据流转示例​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

数据表结构与字段说明

流程实例状态与业务含义

流程实例与业务表单的关联机制

流转控制与撤销机制

查询与数据转换

API 与控制器

依赖关系分析

性能考虑

故障排查指南

结论

附录

典型业务场景与数据流转示例