审批人选了「部门主管」,发起却报 Unknown property:Forge Admin 启动时补齐组织变量

请假单第二岗选的是「部门主管」。申请人填完表单,一点发起,有的环境当时看不出问题,流程走到部门审批时才弹出:

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

  1. 现象(历史) :设计器勾了「上级领导 / 部门主管 / HR」,发起后流程走到该节点才报 Unknown property used in expression,变量名是 initiatorLeader、deptManager 或 hr,实例停在半路。
  2. 根因 :设计器把这三类选项写成同名 JUEL 变量是对的,但启动路径不完整。旧逻辑只尝试注入 initiatorLeader,找不到人就记一条 warn 仍然启动;deptManager 和 hr 根本没有注入。
  3. 改法 :启动时由 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 会这样走:

  1. 设计器写出 flowable:assignee="${deptManager}",回读时仍识别为「部门主管」。
  2. 启动时先写入 initiator、startUserId、startDeptId 等内置变量;若模型里还有「上级领导」,旧逻辑可能先尝试注入 initiatorLeader。
  3. enrich 扫到「部门审批」的 assignee 是 ${deptManager},变量表里还没有值,便按用户 9、部门 12 查询部门主管。单测里这条路径会得到 "200" 并写入 deptManager。
  4. 流程带着这个变量启动。按源码推演,节点创建任务时 ${deptManager} 求值为 200,不再报 Unknown property。
  5. 若三条部门主管路径都是空的:发起直接失败,提示「发起人所在部门未设置部门主管,无法确定审批节点「部门审批」的审批人」,不会留下卡在半路的实例。

若停在 f48efeed5 之前:步骤 3 和 5 都不会发生,deptManager 一直缺席,步骤 4 会在创建任务时炸成标题里的 Unknown property。若节点写的是「上级领导」且发起人没有领导,旧逻辑只会在日志里警告,启动照样成功,到节点时同样失败。

系列说明与仓库

本文是 Forge Admin 审批设计器踩坑系列的一篇,只覆盖 内置组织审批人(上级领导 / 部门主管 / HR)在发起时补齐变量,以及补不齐时拒绝发起。前序可读:转办后的非终态幂等键、子表只读列字段权限、会签 completionCondition、驳回给发起人后的直送跳回、条件分支公共节点合并等。

源码路径速查:

  • 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.js
  • forge-server/.../DesignerApproverVariableSupport.java(enrich / resolve / 提示文案)
  • forge-server/.../FlowInstanceServiceImpl.java(启动时调用 enrich)
  • forge-server/.../FlowStarterContextRequirementResolver.java(旧路径只识别 initiatorLeader)
  • forge-server/.../FlowOrgIntegrationService.java
  • forge-server/.../DesignerApproverVariableSupportTest.java

若这篇帮你对上了「选了部门主管,发起却报 Unknown property」的现场,麻烦点个赞和收藏。你在组织审批人、发起校验或待办快捷同意上还卡过哪一题?评论区丢给我,下一篇优先写读者票最高的坑。

相关推荐
wno7041 小时前
springboot整合FastDFS
java·spring boot·后端
一起_java10 小时前
技术文章-基于Dify-Agent的智能问答系统设计与实现
java·spring boot·后端·agent·dify
Flynn Liang11 小时前
I/O 密集型高并发实战:Java 服务 10 维优化,从线程打满到 10 万 QPS
java·spring boot·性能优化·高并发·系统设计·虚拟线程·io密集型
Flynt18 小时前
掘金热文说 Spring Boot 4.1 默认开虚拟线程,我实测后发现了更狠的坑
java·spring boot·性能优化
杨凯凡1 天前
Spring Boot 事务提交后消息仍会丢?TransactionalEventListener 与 Outbox 可靠投递实战
java·spring boot
Eyfcom1 天前
〖物流低代码实战 03〗物流中台的服务编排与协议转换:从“点对点调用”到“可视化编排”
低代码·快递系统·物流低代码实战
ClouGence1 天前
自动化测试定位不到元素怎么办?
selenium·低代码·测试
学长毕设2 天前
基于SpringBoot军事纪念馆管理系统设计与实现-附源码
java·spring boot·后端
Java小卷2 天前
面向 Schema 编程,Vue 3 页面级渲染引擎!强大的第三方 UI 适配与扩展(一)
vue.js·低代码