部门经理把请假审批转给了候补的同事。待办列表里,原办理人那条不见了,新同事这边也出现了这条任务。对方点开、写下意见、一点同意,界面却弹出:
任务动作幂等冲突,请刷新后重试
刷新再点,还是这句。值班时很容易往三个方向猜:是不是重复提交触发了幂等?转办有没有把任务状态改成已完成?还是 Flowable 把「转办」做成了委派态,complete 之前少了一次 resolve?
Forge Admin(开源后台,仓库见文末)把这件事拆成两层。业务上的「转办」并不走 Flowable 的 delegateTask,而是 setOwner 记下原办理人,再用 setAssignee 把任务交给新办理人,本地任务保持可办理(CLAIMED);转办成功后写在任务上的幂等键,只用来识别原操作者的同一请求重试,不能再把新办理人的同意、驳回或再次转办当成冲突。本文依据仓库 main(HEAD d11acc88,2026-11-15 20:18 Asia/Shanghai)真实源码与提交;委派态须先 resolve 再 complete 的踩坑写于 2026-05-06 的 code-copilot/memory/pitfalls/flow.md,幂等键误伤新办理人由 150bdb5c(2026-11-14 15:55 Asia/Shanghai)修复。未在本轮运行环境复现,推断处标明「按源码推演」,发布前请作者自行点验。
查重:和已发的子表只读列字段权限、会签 completionCondition、驳回直送、条件分支公共节点合并、跨租户短信、在线 DDL、门户入口权限都不是同一题。本篇只谈业务转办的换人协议,以及转办键被误当成终态幂等冲突。
TL;DR
- 现象(历史):转办已经成功,新办理人一点同意、驳回或再次转办,却报「任务动作幂等冲突,请刷新后重试」。授权校验曾把任务上任何残留幂等键都视为终态冲突。
- 根因:转办并不结束任务,但会把幂等键和
actionType=DELEGATE写在本地任务上,用来识别原操作者重试。校验把「有键」等同于「动作已经做完」,新办理人带着新的同意键进来就被拒。另一条更早的坑:若误用 FlowabledelegateTask,任务会进入DelegationState.PENDING,直接complete会报 must be resolved instead。 - 改法:业务转办用
setOwner+setAssignee,状态保持CLAIMED;holdsFinalActionKey对DELEGATE键放行新动作,原操作者的同一请求仍走幂等命中。通过/驳回统一封装:若仍遇到委派待解决态,先resolveTask再complete。设计器权限开关文案已从「允许委派」改为「允许转办」,和待办按钮对齐。
全景:换人、留键、完成
业务「转办」和 Flowable 文档里的「委派(delegate)」不是同一件事。Forge Admin 把换人、授权和完成拆成三条路径:
| 路径 | 关键位置 | 正确形态 |
|---|---|---|
| 业务转办 | FlowTaskActionCoordinator.delegate | setOwner(原办理人) + setAssignee(新办理人),本地 status=CLAIMED,actionType=DELEGATE |
| 幂等授权 | FlowTaskActionAuthorization.holdsFinalActionKey | 只有非 DELEGATE 的残留键才视为终态冲突 |
| 通过 / 驳回 | completeTask | 若 DelegationState.PENDING,先 resolveTask 再 complete |
| 权限文案 | PermissionConfig.vue 的 allowDelegate | 界面展示「允许转办」,字段名仍是 allowDelegate |
按源码推演:转办成功后,任务还在跑,只是办理人换了。幂等键是「原办理人这笔转办请求」的指纹,不是「这条任务已经办结」的锁。两边若被当成同一件事,新办理人就会被自己面前这条仍可办的任务挡住。
方法名和动作类型仍然叫 delegate / DELEGATE,待办按钮和设计器开关却已经改称「转办」。按源码推演,这不是两套实现,而是同一条换人链路:对外说转办,对引擎不走委派态。713fd464(2026-11-14 23:15 Asia/Shanghai)把开关文案从「允许委派 · 审批人可委托他人代审」改成「允许转办 · 审批人可将任务转交他人处理(待办中的「转办」)」,就是为了和这条实现对齐。
坑一:业务转办若走 delegateTask,后续审批会卡在委派态
现象
这是仓库在 2026-05-06 写入 pitfalls 的现场,不是本轮新复现。当时调用 /api/flow/task/reject 驳回一条已经被 taskService.delegateTask 处理过的任务,Flowable 抛出:
A delegated Task ... cannot be completed, but should be resolved instead.
按源码推演:值班时看到这句,很容易继续在驳回接口上找 bug。真正的错位在更前面——「把任务交给另一个人」被做成了 Flowable 的委派语义。
根因(代码)
delegateTask 会把任务置为 DelegationState.PENDING。Flowable 禁止对 PENDING 任务直接 complete,必须先 resolveTask。业务转办的本意是换办理人、任务继续可办,并不是「代办完再交回原拥有者」。把这两件事叠在同一个 API 上,后面的同意和驳回都会踩到委派态。
当前业务转办已经改走换人,不再调用 delegateTask(FlowTaskActionCoordinator.delegate,日志文案就是「转办任务」):
// forge-plugin-flow/.../FlowTaskActionCoordinator.java
String owner = task.getAssignee() != null && !task.getAssignee().isEmpty()
? task.getAssignee()
: userId;
if (owner != null && !owner.isEmpty()) {
taskService.setOwner(taskId, owner);
}
taskService.setAssignee(taskId, targetUserId.trim());
FlowTask flowTask = new FlowTask();
flowTask.setStatus(FlowTaskStatus.CLAIMED.getCode());
flowTask.setAssignee(targetUserId.trim());
flowTask.setOwner(owner);
flowTask.setActionIdempotencyKey(idempotencyKey);
flowTask.setActionRequestDigest(requestDigest);
flowTask.setActionType(idempotencyKey == null ? null : "DELEGATE");
注意三件同时成立的事:引擎侧只改 owner / assignee;本地任务状态仍是 CLAIMED(可办理);若调用方传了幂等键,会把 actionType 写成 DELEGATE。公开方法仍叫 delegate / delegateTask,但实现已经是转办,不是委派。
通过和驳回仍保留了一道防护。按源码推演,历史实例或其它入口仍可能留下 PENDING:
private void completeTask(Task task, Map<String, Object> variables) {
String taskId = task.getId();
if (DelegationState.PENDING.equals(task.getDelegationState())) {
log.info("任务处于委派待解决状态,先 resolve 再 complete:taskId={}, assignee={}, owner={}",
taskId, task.getAssignee(), task.getOwner());
taskService.resolveTask(taskId);
}
// 再 complete ...
}
怎么改
自己封装审批动作时,不要直接把业务「转办」接到 taskService.delegateTask。换人用 setOwner + setAssignee,并同步本地任务表、保持可办理。通过/驳回走到 complete 之前,先看 DelegationState:是 PENDING 就先 resolveTask。Forge Admin 这条链路已经按这个原则落地;若你在扩展里仍直接打 Flowable API,按源码推演还会重新踩到 2026-05-06 那条报错。
坑二:转办留下的幂等键,把新办理人当成冲突
现象
这是 CHANGELOG 在 2026-11-14 记下的现场,修复提交是 150bdb5c(当天 15:55 Asia/Shanghai):转办后被转办人同意或驳回,报「任务动作幂等冲突」。按源码推演:转办接口已经成功,任务办理人已经是新同事,待办也能看到;卡住的是下一步动作的授权,不是换人本身。
根因(代码)
转办是非终态动作:任务还在,只是人换了。为了让原办理人的重复点击不二次换人,系统把幂等键写在这条仍处于 CLAIMED 的任务上。修复前,授权校验把「任务上有幂等键」直接当成冲突:
// 修复前:FlowTaskActionAuthorization
if (task.getActionIdempotencyKey() != null) {
throw new BusinessException("任务动作幂等冲突,请刷新后重试");
}
按源码推演:新办理人带着新的同意键进来,和转办键并不相同,也不是原请求重试;但旧逻辑不区分「终态动作留下的键」和「转办这种还要继续办的键」,于是一律拒绝。刷新解决不了,因为键还在任务上。
当前改成按动作类型判断是否终态键:
// 修复后
private static boolean holdsFinalActionKey(FlowTask task) {
return task.getActionIdempotencyKey() != null
&& !NON_FINAL_ACTION_TYPE_DELEGATE.equals(task.getActionType());
}
授权入口在 authorize:先识别「同一请求重试」,再校验当前办理人,最后才检查终态键。转办后 assignee 已经是新用户,原操作者只有在重试同一笔转办(键、摘要、actionType 都相同,且任务仍是 CLAIMED)时,才允许通过 owner 命中幂等结果;原办理人再用新的同意键去批,会报「当前用户不是任务办理人」。单测 FlowTaskActionAuthorizationTest 覆盖了这三条:shouldLetNewAssigneeActAfterDelegate、shouldStillReplayDelegateRetryFromOriginalOwner、shouldRejectOriginalOwnerNewActionAfterDelegate。
authorizeTaskAction 命中幂等结果时返回 null,协调器直接结束,不会把 setAssignee 再跑一遍。按源码推演,这才能保证「原办理人重复点转办」是重放,而不是第二次换人。
怎么改
给非终态动作留幂等键时,不要用「有键就是冲突」一刀切。终态(同意、驳回、终结)留下的键,应当挡住另一笔不同的请求;转办这种任务还在跑的键,只应识别原请求重试,并放行新办理人的新动作。Forge Admin 用 actionType=DELEGATE 标记这把非终态键。若你在自己的任务镜像表上做了类似幂等字段,按源码推演也需要把「换人」和「办结」分开。
转办后自查清单
遇到「转办成功了,下一步却失败」,可以按这张表对一下。建议收藏后对着自己的引擎和本地任务表逐项看。
| # | 要核对的点 | 怎么判断 |
|---|---|---|
| 1 | 业务转办有没有调用 delegateTask | 应该走 setOwner + setAssignee,不要进入 PENDING |
| 2 | 本地任务状态 | 转办后应仍是可办理(Forge Admin 为 CLAIMED),不是已完成 |
| 3 | 引擎办理人 | assignee 已是新用户,owner 是原办理人 |
| 4 | 报错「must be resolved instead」 | 先看 DelegationState,PENDING 要先 resolveTask 再 complete |
| 5 | 报错「任务动作幂等冲突」 | 看残留键的 actionType 是不是转办;转办键不该挡住新动作 |
| 6 | 原办理人重复点转办 | 同一键、同一摘要应命中幂等,不应再换一次人 |
| 7 | 原办理人转走后再点同意 | 应拒绝(不是当前办理人),不要误放行 |
| 8 | 设计器开关文案 | 与待办按钮一致,应是「允许转办」,不要写成容易误导的「允许委派」 |
| 9 | 单测 | FlowTaskActionAuthorizationTest 里上述三条转办用例应绿 |
跟我对照:从转办到新办理人点同意
假设用户 101 把任务转给用户 202,随后 202 点同意。按源码推演,当前 main 会这样走:
- 101 调用转办:授权通过后,
setOwner("101"),setAssignee("202"),本地状态保持CLAIMED,写入转办幂等键和actionType=DELEGATE。 - 101 若用同一键再点一次转办:
authorize识别为幂等重放,经 owner 校验后直接返回,不再改办理人。 - 202 点同意:任务上虽有转办键,但
holdsFinalActionKey为 false,授权放行;completeTask里若不是PENDING,直接complete。 - 101 转走后再点同意:assignee 已是 202,报「当前用户不是任务办理人」。
若停在 150bdb5c 之前:步骤 3 会在授权阶段被转办键挡住,弹出标题里的「任务动作幂等冲突」。若更早误走 delegateTask:步骤 3 可能通过授权,却在 complete 时收到 must be resolved instead;当前封装会先 resolve 再完成,但业务转办本身不应再走进这条分支。
系列说明与仓库
本文是 Forge Admin 审批设计器踩坑系列的一篇,只覆盖 业务转办(setOwner / setAssignee / 非终态幂等键 / 委派态先 resolve 再 complete)。前序可读:子表只读列字段权限、会签 completionCondition、驳回给发起人后的直送跳回、条件分支公共节点合并等。
- Gitee:gitee.com/ForgeLab/fo…
- GitHub:github.com/yaomindong1…
源码路径速查:
forge-server/.../FlowTaskActionCoordinator.java(delegate、completeTask)forge-server/.../FlowTaskActionAuthorization.java(holdsFinalActionKey)forge-server/.../FlowTaskServiceImpl.java(对外delegate/delegateTask)forge-server/.../FlowTaskActionAuthorizationTest.javaforge-admin-ui/src/components/flow-designer/panel/PermissionConfig.vue(「允许转办」)code-copilot/memory/pitfalls/flow.md第 7 条(2026-05-06)
若这篇帮你对上了「转办成功、下一步却报幂等冲突」的现场,麻烦点个赞和收藏。你在转办、改派、加签或待办快捷同意上还卡过哪一题?评论区丢给我,下一篇优先写读者票最高的坑。