请假单第二岗选的是「部门主管」。申请人填完表单,一点发起,有的环境当时看不出问题,流程走到部门审批时才弹出:
Unknown property used in expression: deptManager
刷新还是这句,实例停在半路。值班时很容易往两头猜:是 BPMN 里审批人表达式写错了,还是 Flowable 根本不认设计器里的「部门主管」?
Forge Admin(开源后台,仓库见文末)在审批设计器里提供了三类内置审批人:上级领导、部门主管、HR。写出的 BPMN 不是某个写死的用户 ID,而是 ${initiatorLeader}、${deptManager}、${hr} 这类流程变量。变量要在发起时按发起人的组织关系补进去;过去部门主管和 HR 从未注入,上级领导找不到时也只打日志就放行。节点创建任务时一求值,Flowable 就会报 Unknown property,流程卡在半路。本文依据仓库 main(HEAD d11acc88,2026-11-15 20:18 Asia/Shanghai)真实源码与提交,主修复是 f48efeed5(2026-11-14 22:48 Asia/Shanghai)。CHANGELOG 把同一天的现场记成:这三类审批人在发起时补齐,找不到即提示原因。未在本轮运行环境复现,推断处标明「按源码推演」,发布前请作者自行点验。
查重:和已发的转办幂等冲突、子表只读列字段权限、会签 completionCondition、驳回直送、条件分支公共节点合并、跨租户短信、在线 DDL、门户入口权限都不是同一题。本篇也不谈「把固定用户 ID 写成变量表达式」那种写法问题,只谈这三类组织审批人变量要在发起时补齐,补不齐就拒绝发起。
TL;DR
- 现象(历史) :设计器勾了「上级领导 / 部门主管 / HR」,发起后流程走到该节点才报
Unknown property used in expression,变量名是initiatorLeader、deptManager或hr,实例停在半路。 - 根因 :设计器把这三类选项写成同名 JUEL 变量是对的,但启动路径不完整。旧逻辑只尝试注入
initiatorLeader,找不到人就记一条 warn 仍然启动;deptManager和hr根本没有注入。 - 改法 :启动时由
DesignerApproverVariableSupport.enrich扫描 userTask,按发起人组织关系补齐这三个变量;调用方已经传入的值会保留。补不齐就抛出带节点名称的业务异常,拒绝发起,避免半路卡死。
全景:设计器选项、变量、发起时补齐
Forge Admin 把「选谁来批」和「变量从哪来」拆开。设计器面板 ApproverAssigneeForm.vue 里,这三项的值就是变量表达式本身:
| 设计器选项 | 写入 BPMN 的 assignee | 发起时怎么补 | 补不齐时(当前) |
|---|---|---|---|
| 上级领导 | ${initiatorLeader} |
先 getLeaderUserIdByLevel(userId, 1),再取 getLeaderUserIds 的第一个 |
拒绝发起:发起人未设置上级领导,无法确定审批节点「...」的审批人 |
| 部门主管 | ${deptManager} |
先按用户取一层部门主管,再取主管列表,再按发起部门 ID 兜底 | 拒绝发起:发起人所在部门未设置部门主管,无法确定审批节点「...」的审批人 |
| HR | ${hr} |
getUserIdsByRoleCode("hr") 的第一个 |
拒绝发起:未找到角色编码为 hr 的人员,无法确定审批节点「...」的 HR 审批人 |
按源码推演:新模型里「指定人员」走的是字面量用户 ID,不走这张表;历史模型里把固定用户写成 ${user_数字} 的兼容补齐,也是另一条路径。本篇只覆盖上表这三类内置组织审批人。

坑 1:部门主管和 HR 写对了,启动却没把变量放进去
现象
设计器里明明选了「部门主管」或「HR」,发布后的 BPMN 里也能看到对应的 flowable:assignee="${deptManager}" 或 ${hr}。按源码推演,流程可以启动成功,一走到这个 userTask,引擎求值失败,报 Unknown property,实例留在半路。
根因(代码)
设计器转换层把这四个静态变量(加上「发起人」${initiator})收进同一个集合,写出时原样放到 flowable:assignee 上,并不额外写 assigneeType:
js
// user-task-writer.js
const STATIC_ASSIGNEES = new Set([
`${initiator}`,
`${initiatorLeader}`,
`${deptManager}`,
`${hr}`,
])
// ...
else if (STATIC_ASSIGNEES.has(cfg.assignee)) {
val = cfg.assignee
}
回读时 user-task-parser.js 用同一份集合识别,所以画布上再打开,仍显示「部门主管」,并不是丢了配置。发起人变量 initiator 在启动时本来就会写入;问题出在另外三个要查组织关系的变量。
启动流程时,FlowInstanceServiceImpl 会注入发起人、部门、标题等内置变量,并按流程定义扫描是否需要上级领导。旧逻辑只覆盖 initiatorLeader,而且失败是软的:
java
// FlowInstanceServiceImpl 启动流程(历史行为仍保留在这段之后)
if (contextRequirements.leader()
&& userId != null && !userId.isEmpty() && flowOrgIntegrationService != null) {
// 取到领导才 vars.put("initiatorLeader", leaderId)
// 找不到或查询失败:只 log.warn,initiatorLeader 变量未注入
}
这段还受 FlowStarterContextRequirementResolver 约束:解析器只在 BPMN 文本里搜 initiatorLeader,用来决定要不要查上级。它并不识别 deptManager 和 hr。按源码推演,一张只配了「部门主管」或「HR」、没有「上级领导」的流程,连这条旧注入都不会走,两个变量会一直缺到节点求值。
组织关系本身不是空白:FlowOrgIntegrationService 已经提供了 getDeptManagerUserIdByLevel、getDeptManagerUserIds、getDeptManagerByDeptId、getUserIdsByRoleCode。缺的是启动时把查询结果写进流程变量。
怎么改
不要等节点创建任务时再碰这些变量。发起时先读 BPMN 里的 userTask,把确实用到的内置变量补齐。当前 DesignerApproverVariableSupport.enrich 只匹配 assignee 整段为 ${initiatorLeader} / ${deptManager} / ${hr}(允许空白),其它 SPEL 或字面量 ID 不会被误伤。单测 keepsCallerProvidedValuesAndIgnoresOtherAssignees 覆盖了这一点:已有的 deptManager 会保留,字面量 "42" 和 ${flowSpelService.getInitiator(execution)} 都不会触发查询。
坑 2:上级领导找不到,旧逻辑只打日志就把单子发出去
现象
这是 CHANGELOG 在 2026-11-14 记下的现场,修复提交是 f48efeed5(当天 22:48 Asia/Shanghai):审批人写成上级领导、部门主管或 HR 时,要在发起时补齐;补不齐要直接提示。按源码推演,修复前如果发起人没有上级,启动仍会成功,只在日志里看到「未找到发起人的上级领导,initiatorLeader 变量未注入」。等流程走到该节点,才变成 Unknown property。值班时对上日志和界面报错要绕一圈。
根因(代码)
旧注入把「没找到人」当成可继续的警告,而不是启动失败。Flowable 对缺失的 JUEL 属性是硬失败,不会把空变量当成「暂无审批人」。于是启动阶段的宽容,变成运行阶段的卡死。
部门主管和 HR 比上级领导更隐蔽:它们连 warn 都没有,因为根本没人去查。
怎么改
补齐和校验放到启动入口,紧跟在历史固定审批人兼容补齐之后:
java
DesignerApproverVariableSupport.enrich(bpmnModel, vars, userId, deptId, flowOrgIntegrationService);
补不齐时不再放行,而是抛出 BusinessException,文案带上节点名称,例如「发起人所在部门未设置部门主管,无法确定审批节点「部门审批」的审批人」。单测 refusesToStartWhenTheInitiatorHasNoLeader 断言的就是这条提示。
解析规则按源码是:
- 上级领导:
getLeaderUserIdByLevel(userId, 1),否则getLeaderUserIds(userId)的第一个非空值 - 部门主管:先
getDeptManagerUserIdByLevel(userId, 1),再getDeptManagerUserIds(userId),再getDeptManagerByDeptId(deptId) - HR:
getUserIdsByRoleCode("hr")的第一个非空值;角色编码写死为hr
按源码推演:若租户里人事角色的编码不是 hr,即便组织里已经有人事人员,发起仍会提示找不到角色编码为 hr 的人员。发布前请对照自己环境的角色编码。调用方若在启动参数里已经传入同名变量且非空,enrich 会跳过查询,不覆盖已有值。
组织审批人自查清单
遇到「设计器里选了部门主管 / 上级领导 / HR,发起后却报 Unknown property」,可以按这张表对一下。建议收藏后对着自己的模型 XML 和启动变量逐项看。
| # | 要核对的点 | 怎么判断 |
|---|---|---|
| 1 | BPMN 里的 assignee | 应是 ${deptManager}、${initiatorLeader} 或 ${hr},不要和指定人员的字面量 ID 混在一起查 |
| 2 | 启动变量里有没有同名键 | 发起成功后,流程变量应已有对应的用户 ID |
| 3 | 报错出现的时机 | 修复后应在发起时就被拒绝;若已经启动成功、走到节点才报 Unknown property,说明变量仍没补上 |
| 4 | 上级领导查不到 | 不应再只写日志就放行;应提示「发起人未设置上级领导」并带节点名 |
| 5 | 部门主管查不到 | 应提示所在部门未设置部门主管;可核对用户主管、主管列表和发起部门 ID 三条路径 |
| 6 | HR 查不到 | 先核对是否存在角色编码恰好为 hr 的人员,不要只看角色中文名 |
| 7 | 调用方预传的变量 | 非空值应被保留,不应被组织查询覆盖 |
| 8 | 其它表达式 | 自定义 SPEL、固定用户 ID 不应走这条补齐;不要为了「万能注入」放开匹配范围 |
| 9 | 单测 | DesignerApproverVariableSupportTest 里解析、拒绝发起、保留已有值三条应绿 |
跟我对照:从勾选部门主管到发起
假设请假流程有一个名为「部门审批」的节点,设计器选了「部门主管」,发起人是用户 9、部门 12。按源码推演,当前 main 会这样走:
- 设计器写出
flowable:assignee="${deptManager}",回读时仍识别为「部门主管」。 - 启动时先写入
initiator、startUserId、startDeptId等内置变量;若模型里还有「上级领导」,旧逻辑可能先尝试注入initiatorLeader。 enrich扫到「部门审批」的 assignee 是${deptManager},变量表里还没有值,便按用户 9、部门 12 查询部门主管。单测里这条路径会得到"200"并写入deptManager。- 流程带着这个变量启动。按源码推演,节点创建任务时
${deptManager}求值为200,不再报 Unknown property。 - 若三条部门主管路径都是空的:发起直接失败,提示「发起人所在部门未设置部门主管,无法确定审批节点「部门审批」的审批人」,不会留下卡在半路的实例。
若停在 f48efeed5 之前:步骤 3 和 5 都不会发生,deptManager 一直缺席,步骤 4 会在创建任务时炸成标题里的 Unknown property。若节点写的是「上级领导」且发起人没有领导,旧逻辑只会在日志里警告,启动照样成功,到节点时同样失败。
系列说明与仓库
本文是 Forge Admin 审批设计器踩坑系列的一篇,只覆盖 内置组织审批人(上级领导 / 部门主管 / HR)在发起时补齐变量,以及补不齐时拒绝发起。前序可读:转办后的非终态幂等键、子表只读列字段权限、会签 completionCondition、驳回给发起人后的直送跳回、条件分支公共节点合并等。
- Gitee:gitee.com/ForgeLab/fo...
- GitHub:github.com/yaomindong1...
源码路径速查:
forge-admin-ui/src/components/flow-designer/panel/ApproverAssigneeForm.vue(上级领导 / 部门主管 / HR)forge-admin-ui/src/components/flow-designer/converter/user-task-writer.js(STATIC_ASSIGNEES)forge-admin-ui/src/components/flow-designer/converter/user-task-parser.jsforge-server/.../DesignerApproverVariableSupport.java(enrich/resolve/ 提示文案)forge-server/.../FlowInstanceServiceImpl.java(启动时调用enrich)forge-server/.../FlowStarterContextRequirementResolver.java(旧路径只识别initiatorLeader)forge-server/.../FlowOrgIntegrationService.javaforge-server/.../DesignerApproverVariableSupportTest.java
若这篇帮你对上了「选了部门主管,发起却报 Unknown property」的现场,麻烦点个赞和收藏。你在组织审批人、发起校验或待办快捷同意上还卡过哪一题?评论区丢给我,下一篇优先写读者票最高的坑。