转办给同事后对方一点同意就报幂等冲突:Forge Admin 不把转办键当成终态

部门经理把请假审批转给了候补的同事。待办列表里,原办理人那条不见了,新同事这边也出现了这条任务。对方点开、写下意见、一点同意,界面却弹出:

任务动作幂等冲突,请刷新后重试

刷新再点,还是这句。值班时很容易往三个方向猜:是不是重复提交触发了幂等?转办有没有把任务状态改成已完成?还是 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

  1. 现象(历史):转办已经成功,新办理人一点同意、驳回或再次转办,却报「任务动作幂等冲突,请刷新后重试」。授权校验曾把任务上任何残留幂等键都视为终态冲突。
  2. 根因 :转办并不结束任务,但会把幂等键和 actionType=DELEGATE 写在本地任务上,用来识别原操作者重试。校验把「有键」等同于「动作已经做完」,新办理人带着新的同意键进来就被拒。另一条更早的坑:若误用 Flowable delegateTask,任务会进入 DelegationState.PENDING,直接 complete 会报 must be resolved instead。
  3. 改法 :业务转办用 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,日志文案就是「转办任务」):

java 复制代码
// 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:

java 复制代码
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 的任务上。修复前,授权校验把「任务上有幂等键」直接当成冲突:

java 复制代码
// 修复前:FlowTaskActionAuthorization
if (task.getActionIdempotencyKey() != null) {
    throw new BusinessException("任务动作幂等冲突,请刷新后重试");
}

按源码推演:新办理人带着新的同意键进来,和转办键并不相同,也不是原请求重试;但旧逻辑不区分「终态动作留下的键」和「转办这种还要继续办的键」,于是一律拒绝。刷新解决不了,因为键还在任务上。

当前改成按动作类型判断是否终态键:

java 复制代码
// 修复后
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 会这样走:

  1. 101 调用转办:授权通过后,setOwner("101"),setAssignee("202"),本地状态保持 CLAIMED,写入转办幂等键和 actionType=DELEGATE。
  2. 101 若用同一键再点一次转办:authorize 识别为幂等重放,经 owner 校验后直接返回,不再改办理人。
  3. 202 点同意:任务上虽有转办键,但 holdsFinalActionKey 为 false,授权放行;completeTask 里若不是 PENDING,直接 complete。
  4. 101 转走后再点同意:assignee 已是 202,报「当前用户不是任务办理人」。

若停在 150bdb5c 之前:步骤 3 会在授权阶段被转办键挡住,弹出标题里的「任务动作幂等冲突」。若更早误走 delegateTask:步骤 3 可能通过授权,却在 complete 时收到 must be resolved instead;当前封装会先 resolve 再完成,但业务转办本身不应再走进这条分支。

系列说明与仓库

本文是 Forge Admin 审批设计器踩坑系列的一篇,只覆盖 业务转办(setOwner / setAssignee / 非终态幂等键 / 委派态先 resolve 再 complete)。前序可读:子表只读列字段权限、会签 completionCondition、驳回给发起人后的直送跳回、条件分支公共节点合并等。

源码路径速查:

  • forge-server/.../FlowTaskActionCoordinator.java(delegate、completeTask)
  • forge-server/.../FlowTaskActionAuthorization.java(holdsFinalActionKey)
  • forge-server/.../FlowTaskServiceImpl.java(对外 delegate / delegateTask)
  • forge-server/.../FlowTaskActionAuthorizationTest.java
  • forge-admin-ui/src/components/flow-designer/panel/PermissionConfig.vue(「允许转办」)
  • code-copilot/memory/pitfalls/flow.md 第 7 条(2026-05-06)

若这篇帮你对上了「转办成功、下一步却报幂等冲突」的现场,麻烦点个赞和收藏。你在转办、改派、加签或待办快捷同意上还卡过哪一题?评论区丢给我,下一篇优先写读者票最高的坑。

相关推荐
北风toto4 小时前
Spring Boot 常用注解 · 概要笔记
spring boot·笔记·后端
宋冠巡4 小时前
Spring Boot 4 + OpenTelemetry + Spring Cloud Gateway:全链路 TraceId 传播验证
spring boot·可观测性·traceid
下一站春风里5 小时前
Spring IoC 控制反转 完整技术笔记
java·spring boot·笔记·spring
小码哥0685 小时前
Spring Boot在线租房系统源码:UniApp找房、VR展示与预约管理落地解析
spring boot·租房小程序·租房系统·在线租房
芜名氏5 小时前
API 文档生成工具——SpringDoc
java·spring boot·ci/cd·设计规范
CORNERSTONE36512 小时前
集团调整组织架构后,审批人和数据权限怎么一起改?
低代码·权限管理·流程管理
乌暮1 天前
Spring AOP 与 Spring 事务:用大白话彻底理解原理与实践
java·数据库·spring boot·后端·sql·学习·spring
小荷才露尖尖角,早有蜻蜓立上头1 天前
SpringBoot+QQ邮箱发送邮件
spring boot
头发还在的女程序员1 天前
Java在线租房系统源码解析:Spring Boot+Vue 3+UniApp房源管理与预约看房方案
java·vue.js·spring boot·租房小程序·租房系统·租房软件