主题
流程引擎底座 概要设计文档
文档版本：1.01 ｜ 最近核对日期：2026-11-04
架构位置
流程引擎底座由三部分组成：
| 组成 | 位置 | 职责 |
|---|---|---|
| 引擎适配层 | digital-construction-modules/digital-construction-workflow | Warm-Flow 引擎的平台化封装：分类、定义、实例、任务、SpEL、监听、消息与 LiteFlow 编排 |
| 业务契约层 | digital-construction-api（com.bokun.workflow.api） | 面向业务模块的稳定契约：WorkflowService 门面、StartProcessDTO/CompleteTaskDTO、流程事件 |
| 前端工作台 | digital-construction-ui（views/workflow、api/workflow、components/Process 等） | 管理端页面、审批工作台、办理面板、流程图与通用选人组件 |
引擎本体为 Warm-Flow（org.dromara.warm.flow），运行时表、监听机制与办理语义以框架为准；本模块只做平台化适配，不改写引擎内核。整体开关由 warm-flow.enabled=true 控制，全部底座 Bean 通过 @ConditionalOnEnable 条件装配。
模块边界
- 底座负责：流程分类/定义/版本管理、任务流转与办理动作、节点扩展与按钮权限、动态办理人解析、抄送与消息通知、流程状态与事件发布、统一流程图查看。
- 业务模块负责：发起入口与业务表单、业务校验、
businessId关联、监听ProcessEvent/ProcessTaskEvent维护业务状态、各自流程 JSON 的编排（遵循流程图编排规范）。 - 系统模块提供：用户/部门/岗位数据（办理人候选）、字典（任务状态
wf_task_status）、消息通道（站内信/邮箱/短信）。
业务模块不复制"我的任务"列表，不在业务表内重复维护审批人快照作为权限依据；引擎当前任务关联关系是办理人判定唯一事实源。
核心流程
任务流转的核心链路由 LiteFlow 编排（resources/liteflow/*.el.xml），组件位于 liteflow/ 包：
| 链 | 编排 | 说明 |
|---|---|---|
startProcessChain | 初始化请求并查已有实例 → 已存在则续提交返回当前任务；否则加载定义、补齐变量、启动实例、保存业务扩展 | 支持草稿续提交 |
completeTaskChain | 加载任务实例、补齐变量并解析办理人 → 执行当前任务跳转 → 开启自动审批时继续办理当前处理人后续任务 | 办理/退回共用一条链 |
taskOperationChain | 解析操作类型、校验入参 → 加载任务并校验操作约束 → 执行操作 → 配置消息类型时发送通知 | 委派/转办/加签/减签 |
deleteInstanceChain | 按业务或实例 ID 加载 → 校验权限并发布业务删除事件 → 按运行/历史模式删除 | 业务单据删除联动 |
状态模型
流程实例状态（FLOW_STATUS，与 Warm-Flow BusinessStatusEnum 一致）：0 待提交、1 审批中、2 审批通过、4 终止、5 作废、6 撤销、8 已完成、9 已退回、10 失效、11 拿回。
关键状态迁移：
- 启动/续提交：0 → 1（提交动作由
submit变量标识申请人节点办理）。 - 全部任务办结：1 → 8（
determineFlowStatus判定任务结束并回写）。 - 画线驳回且目标为申请节点：1 → 9，并仅发送"已退回"结果消息。
- 撤销（取消申请）、终止、作废、拿回、失效由对应动作或管理操作触发。
事件与扩展模型
| 事件 | 发布时机 | 消费方 |
|---|---|---|
ProcessEvent（com.bokun.workflow.api.event） | 总体状态变化：草稿、撤销、退回、作废、终止、已完成；携带 flowCode、businessId、节点信息、状态、办理参数、是否申请人节点 | 业务模块监听，更新单据状态 |
ProcessTaskEvent | 新待办节点产生 | 业务模块监听，维护节点级业务状态/提醒 |
ProcessDeleteEvent | 流程实例删除 | 业务模块清理关联数据 |
WorkflowTaskCompletingEvent | 任务办理中（引擎侧回调） | 底座内部 |
WorkflowCopyEvent | 办理/退回且变量含抄送 | 底座副作用监听器落抄送记录 |
WorkflowTaskMessageEvent / WorkflowResultMessageEvent | 办理/退回后、流程完成或退回时 | 底座副作用监听器按消息类型发送通知 |
全局监听器 WorkflowGlobalListener（实现 Warm-Flow GlobalListener）承担节点扩展解析、动态办理人、事件发布与消息收敛：
start：解析节点ext扩展配置（抄送人集合、扩展变量），分派WorkflowTaskStartHandler业务扩展点。assignment：解析正向/驳回指定办理人变量（PASS:节点码/BACK:节点码，正向消费一次）、动态${nextHandlerId}；申请节点强制置发起人为办理人。finish：判定最终状态并发布ProcessEvent/ProcessTaskEvent，处理抄送、待办消息与结果消息去重（退回发起人场景不叠加待办提醒），消费后清理一次性变量。
节点扩展配置（ext）承载：按钮权限（弹窗选人、委托、转办、抄送、退回、加签、减签、终止、附件上传）与抄送设置、扩展变量。WarmFlowConfig 在全部单例就绪后补注册全局监听器，避免 Bean 创建顺序导致监听器永久为空。
依赖
| 依赖 | 用途 |
|---|---|
| Warm-Flow（mybatis-plus 适配） | 引擎内核与 FLOW_* 运行时表 |
| LiteFlow | 启动/办理/任务操作/删除四条编排链 |
digital-construction-system（UserService） | 办理人候选、昵称翻译、发起人信息 |
| 消息能力（站内信/邮箱/短信） | 待办与结果通知 |
字典 wf_task_status | 任务状态展示 |
权限方案
- 管理端接口按权限码鉴权，与菜单/按钮权限逐字一致：
workflow:category:*、workflow:definition:*、workflow:instance:*、workflow:spel:*；任务侧为workflow:task:list、workflow:task:edit。 - 任务办理不依赖菜单权限码，按"当前任务办理人 + 流程状态 + 节点类型"校验；系统后台自动办理通过
ignore变量显式豁免办理权限。 - 节点按钮权限只控制前端动作展示与提交入口，后端仍执行状态、归属与类型校验，隐藏按钮不等于授权。
关键技术决策
- 门面收敛：业务模块只面向
com.bokun.workflow.api.WorkflowService，不直接调用 Warm-Flow 内部服务，避免引擎升级外溢。 - LiteFlow 编排：启动、办理、任务操作、删除四条链组件化，前置校验与副作用分离，便于按业务扩展（组件在
liteflow/包独立可测）。 - 事件驱动集成：业务模块以 Spring 事件接收流程状态，单向依赖底座契约；底座不回查业务表。
- 流程变量承载动态行为：办理人指定、抄送、消息类型、自动审批、权限豁免等一次性参数通过流程变量传递，消费后清理，避免残留影响后续节点。
- 图表提示统一：实例图节点提示由底座
ChartExtService实现（同时读取历史任务与运行任务），业务模块不重复实现。