主题
流程引擎底座 详细设计文档
文档版本：1.01 ｜ 最近核对日期：2026-11-04
本文记录底座的页面与路由、接口契约、关键类与调用链、流程变量约定和异常/事务边界。业务规则见需求分析，架构与流程模型见概要设计。
装配与开关
- 全部后端组件通过
@ConditionalOnEnable条件装配，warm-flow.enabled=true时生效。 WarmFlowConfig实现SmartInitializingSingleton：Warm-Flow 初始化可能早于业务全局监听器实例化，全部单例就绪后补执行FlowEngine.initGlobalListener，防止引擎永久持有空监听器。- LiteFlow 链定义在
resources/liteflow/：startProcessChain、completeTaskChain、taskOperationChain（task-chain.el.xml）、deleteInstanceChain（instance-chain.el.xml）。
页面与路由
| 页面 | 路由/文件 | 功能 |
|---|---|---|
| 流程分类 | views/workflow/category/index.vue | 分类树维护、导出 |
| 流程定义 | views/workflow/processDefinition/index.vue | 定义列表（左侧分类树）、新增/修改/删除/复制/导入/导出/发布/取消发布/激活/挂起 |
| 流程设计器 | views/workflow/processDefinition/design.vue，固定路由 /workflow/design/index | 定义可视化编辑（CLASSICS 模型），从定义列表「修改流程/查看流程」进入；路由固定注册于 src/router/index.ts，不依赖菜单 |
| 流程实例 | views/workflow/processInstance/index.vue | 运行中/已完成实例、变量、当前办理人、作废/删除 |
| SpEL 表达式 | views/workflow/spel/index.vue | 表达式维护与预览 |
| 我的待办 | views/workflow/task/taskWaiting.vue | 待办列表、办理入口 |
| 我的已办 | views/workflow/task/taskFinish.vue | 已办列表 |
| 我的发起 | views/workflow/task/myDocument.vue | 发起实例、取消申请 |
| 我的抄送 | views/workflow/task/taskCopyList.vue | 抄送记录 |
| 所有待办 | views/workflow/task/allTaskWaiting.vue | 全平台待办、修改办理人、催办 |
办理页组件复用：办理动作面板 components/Process/FlowActionPanel.vue、审批时间线 FlowTimeline.vue、流程图 flowChart.vue（入口 components/FlowChartEntry）、下一办理人选择 components/NextHandlerPicker（基于通用 UserSelect）。业务流程办理页按业务归属在 src/router/flowFormRoutes.ts 固定注册，选人规范见流程图编排规范·流程办理界面与选人。
接口契约
后端路径前缀 /workflow；权限码以 @SaCheckPermission 与 SYS_MENU.PERMS 逐字一致为准。
任务 /workflow/task（FlwTaskController）
| 接口 | 权限码 | 说明 |
|---|---|---|
POST /startWorkFlow | 任务发起入口 | 启动流程，返回实例与首个任务；入参 StartProcessBo（businessId、flowCode、variables、handler、bizExt） |
POST /completeTask | 任务归属校验 | 办理任务；CompleteTaskBo（任务 ID、办理意见、消息类型、办理人、变量、附件） |
GET /pageByTaskWait、/pageByTaskFinish、/pageByTaskCopy | — | 我的待办/已办/抄送分页 |
GET /pageByAllTaskWait、/pageByAllTaskFinish | workflow:task:list | 所有待办/已办分页 |
GET /getTask/{taskId} | — | 任务详情 |
POST /getNextNodeList | — | 下一节点列表（选人/预览） |
POST /terminationTask | — | 终止流程 |
POST /taskOperation/{taskOperation} | 任务归属校验 | 运行时任务操作：delegateTask 委派、transferTask 转办、addSignature 加签、reductionSignature 减签 |
PUT /updateAssignee/{userId} | workflow:task:edit | 修改办理人 |
POST /backProcess | 任务归属校验 | 退回到指定节点 |
GET /getBackTaskNode/{taskId}/{nowNodeCode} | — | 可退回节点列表 |
GET /currentTaskAllUser/{taskId} | — | 当前节点候选办理人 |
POST /urgeTask | workflow:task:edit | 催办 |
实例 /workflow/instance（FlwInstanceController）
| 接口 | 权限码 | 说明 |
|---|---|---|
GET /pageByRunning、/pageByFinish | workflow:instance:list | 运行中/已完成实例分页 |
GET /pageByCurrent | workflow:instance:currentList | 当前办理人相关实例 |
GET /getInfo/{businessId} | workflow:instance:query | 按业务单据查实例详情 |
DELETE /deleteByBusinessIds/{businessIds}、/deleteByInstanceIds/{instanceIds} | workflow:instance:remove | 删除实例（含历史） |
DELETE /deleteHisByInstanceIds/{instanceIds} | workflow:instance:remove | 仅删除历史任务 |
PUT /cancelProcessApply | — | 发起人取消申请 |
PUT /active/{id} | workflow:instance:active | 激活/挂起切换 |
POST /invalid | workflow:instance:invalid | 作废 |
GET /instanceVariable/{instanceId}、PUT /updateVariable | workflow:instance:variableQuery / workflow:instance:variable | 变量查询/更新 |
GET /flowHisTaskList/{businessId} | — | 业务单据历史任务 |
定义 /workflow/definition（FlwDefinitionController）与分类 /workflow/category（FlwCategoryController）
| 接口 | 权限码 |
|---|---|
GET /definition/list、/definition/unPublishList、GET /definition/{id}、GET /definition/xmlString/{id} | workflow:definition:list / workflow:definition:query |
POST /definition、PUT /definition | workflow:definition:add / workflow:definition:edit |
PUT /definition/publish/{id}、PUT /definition/unPublish/{id} | workflow:definition:publish |
DELETE /definition/{ids} | workflow:definition:remove |
POST /definition/copy/{id} | workflow:definition:copy |
POST /definition/importDef、POST /definition/exportDef/{id} | workflow:definition:import / workflow:definition:export |
PUT /definition/active/{id} | workflow:definition:active（激活/挂起） |
GET /category/list、GET /category/{categoryId}、GET /category/categoryTree | workflow:category:list / workflow:category:query |
POST /category、PUT /category | workflow:category:add / workflow:category:edit |
DELETE /category/{categoryId} | workflow:category:remove |
POST /category/export | workflow:category:export |
SpEL /workflow/spel（FlwSpelController）
| 接口 | 权限码 |
|---|---|
GET /spel/list、GET /spel/{id} | workflow:spel:list / workflow:spel:query |
POST /spel、PUT /spel、DELETE /spel/{ids} | workflow:spel:add / workflow:spel:edit / workflow:spel:remove |
业务契约 com.bokun.workflow.api
WorkflowService 门面：startWorkFlow(StartProcessDTO)、completeTask(CompleteTaskDTO)、startCompleteTask(StartProcessDTO)（启动并办理首节点，类级事务）、deleteInstance(businessIds)、getBusinessStatus(businessId)、getBusinessStatusByTaskId(taskId)、setVariable/instanceVariable、getInstanceIdByBusinessId、getFlowVersionByBusinessId(businessId, flowCode)（实例未建时回查当前发布版本）、listCurrentTaskIds(businessIds, userId)、currentTaskAssigneeIds(businessIds)、getTaskNodeCode(taskId)。
关键类与调用链
| 类 | 职责 |
|---|---|
service.impl.WorkflowServiceImpl | 契约门面实现，委托 IFlwTaskService/IFlwInstanceService |
service.impl.FlwTaskServiceImpl | 任务办理、退回、任务操作、启动；驱动 LiteFlow 链 |
| `liteflow.start | complete |
listener.WorkflowGlobalListener | Warm-Flow 全局监听：start 解析节点扩展、assignment 解析办理人、finish 发布事件与消息收敛 |
listener.WorkflowSideEffectListener | 抄送落库、待办消息、结果消息的副作用消费 |
listener.WorkflowTaskStartHandler | 任务开始扩展点接口，业务可注册实现 |
handler.FlowProcessEventHandler | 引擎回调 → 发布 ProcessEvent/ProcessTaskEvent/ProcessDeleteEvent |
handler.WorkflowPermissionHandler | 办理权限判定（任务归属、流程状态、豁免变量） |
handler.WorkflowTaskCompletionEventPublisher | 任务完成事件发布 |
service.impl.FlwChartExtServiceImpl | Warm-Flow ChartExtService：流程图节点提示合并历史任务与运行任务 |
rule.SpelRuleComponent / service.impl.FlwSpelServiceImpl | 网关条件 SpEL 执行与表达式维护 |
service.impl.FlwNodeExtServiceImpl | 节点 ext 扩展配置解析（按钮权限、抄送、变量） |
办理主链路：FlwTaskController.completeTask → FlwTaskServiceImpl → completeTaskChain（准备/执行/自动续办）→ 引擎任务跳转 → WorkflowGlobalListener.finish → FlowProcessEventHandler 发布 ProcessEvent/ProcessTaskEvent → 业务监听器；同时 WorkflowSideEffectListener 消费 WorkflowCopyEvent、WorkflowTaskMessageEvent、WorkflowResultMessageEvent。
流程变量约定（FlowConstant）
| 变量 | 用途 |
|---|---|
businessId、businessCode、initiator、initiatorDeptId | 业务关联与发起人上下文 |
nextHandlerId | 动态下一办理人（节点权限表达式 ${nextHandlerId}） |
PASS:<节点码> / BACK:<节点码> | 办理/退回时指定的该节点办理人；正向消费一次并从实例变量与引擎侧清理，驳回指定人保留供重复驳回 |
flowCopyList、messageType、messageNotice、submit、autoPass | 抄送列表、消息类型（1 站内信/2 邮箱/3 短信）、通知内容、申请人提交标识、自动续办 |
ignore、ignoreDepute、ignoreCooperate | 系统后台办理的权限/委派/会签票签校验豁免 |
__workflowSourceNodeCode、__workflowSourceNodeName | 任务事件内部元数据：来源（刚办理）节点，避免业务监听器把当前办理信息误判为下一节点 |
一次性变量在 finish 消费后统一从引擎移除，防止残留影响后续节点办理。
异常与事务
- 办理入口统一校验：任务存在性、当前办理人归属、流程状态（非终态）、节点类型约束（如加签/减签限会签或票签），不满足返回业务异常，不静默降级。
WorkflowServiceImpl.startCompleteTask类级@Transactional，保证"启动 + 首节点办理"原子性；删除实例链先发布ProcessDeleteEvent再执行删除，业务模块在自身事务内清理关联数据。WarmFlowConfig补注册全局监听器属于启动期自愈，不依赖运行时重试。- 后台自动办理无登录用户上下文，通过
ignore显式豁免权限；仅限系统内调用，接口侧仍按任务归属校验用户发起的办理。
流程定义资源
各业务流程 JSON 位于 digital-construction-modules/digital-construction-workflow/src/main/resources/flow/<业务域>/（如 bidding、planning、survey、engineering-change、cost-unit、investment、operation-dock、quality、sqe、czw、engineering-procedure），通过 importDef 导入发布。编排、锚点与版本规则遵循流程图编排规范，双环境同步步骤见表结构与流程定义双环境同步。