工作流常见问题

流程启动失败

流程定义不存在

现象：调用启动 API 报错 "Process definition not found"。

排查：

1. 确认模型已发布，在「模型管理」中查看版本历史
2. 确认 processKey 与模型 Key 一致
3. 确认流程定义未被挂起

业务键重复

现象：启动报错 "BusinessKey already exists"。

解决：同一业务键在同一流程定义中只能有一个运行中的实例。确认前一次流程是否已结束，或使用不同的业务键。

任务无法提交

处理人不是当前用户

现象：点击提交报错 "You are not the assignee"。

排查：

1. 确认当前用户是任务的 assignee 或候选人
2. 如果是候选人，需要先「认领」任务再处理
3. 检查审批人配置是否正确

流程变量缺失

现象：提交时报错条件表达式执行失败。

解决：检查排他网关条件中引用的变量是否在流程启动时或前序节点中设置。

回调未触发

现象：流程结束后 @FlowCallback 方法未执行。

排查：

1. 确认注解的 processKey 与流程定义 Key 一致
2. 确认方法所在的类已注册为 Spring Bean（@Component）
3. 确认方法签名为 public void method(FlowContext context)
4. 查看后端日志是否有异常信息
5. 确认流程正常结束（非被强制终止）

版本升级后旧实例报错

现象：发布新版本后，旧实例流转到某个节点时报错。

排查：

1. 检查新版本是否删除了旧实例当前停留的节点
2. 检查审批人配置是否变更为不存在的用户或角色
3. 检查流程变量是否在新版本中被移除

解决：

• 恢复被删除的节点（发布新版本补回）
• 或手动终止受影响的旧实例，重新发起

审批人列表为空

现象：任务创建后没有处理人。

排查：

1. 指定人员方式：确认用户未被删除或禁用
2. 指定角色方式：确认角色下有启用的用户
3. 部门负责人方式：确认发起人有所属部门且部门已配置负责人
4. 动态脚本方式：检查表达式执行结果是否为空

流程图不显示

现象：流程追踪页面流程图空白。

解决：

1. 确认模型已正确发布
2. 清除浏览器缓存后刷新
3. 检查 forge-flow 服务是否正常运行

任务认领后无法撤销

现象：用户认领任务后想退回，但没有操作入口。

说明：Forge 默认不支持认领撤销。如需退回，请联系管理员通过后台将该任务的 assignee 置空。