Files
aibridge/docs/workflow/07-troubleshooting.md
T
2026-05-18 09:28:15 +08:00

4.2 KiB
Raw Blame History

故障排查

来源:workflow-guide.md 踩坑记录、后端源码分析、工作流开发实践

常见错误

1. create_template 必须包含 flowXml/flowNodes/flowConfig

问题:调用 create_template 后报 "数据不存在"

原因:create_template 内部调用 flowUtil.create(),如果 flowNodes 为 null,会导致 NPE,templateJson 条目未创建

解决:使用 create_simple_flow() 或确保传入完整参数

# 错误
client.workflow.create_template({
    "fullName": "test",
    "enCode": "test",
    "type": 1,
})

# 正确
client.workflow.create_simple_flow(
    full_name="test",
    en_code="test",
    form_id="form_id",
    approver_user_ids=["user_id"],
)

2. 审批需要 status 字段

问题:audit 调用不生效

原因:缺少 status 字段

解决:使用 approve() / reject() 或显式传入 status

# 正确
client.workflow.audit(operator_id, {
    "status": 1,  # 1=同意, 2=拒绝
    "handleOpinion": "同意",
})

3. launch_task 的 isFlow 必须是整数

问题:Cannot deserialize value of type java.lang.Integer from Boolean

原因:Python True 序列化为 JSON true,Java 无法反序列化

解决:AIBridge 内部使用整数 1

# 正确 - AIBridge 内部处理
client.workflow.launch_task(version_id, {"f_amount": 5000})

# 错误 - 不要手动传布尔值
# client.request("POST", "/api/workflow/task", data={"isFlow": True})  # ✗

4. formData 必须传 dict

问题:"系统异常" 或数据取不到

原因:formData 后端类型为 Map<String, Object>,传 JSON 字符串会解析失败

解决:直接传 dict,不做序列化

# 正确
client.workflow.launch_task(version_id, {"f_amount": 5000})

# 错误
# client.workflow.launch_task(version_id, json.dumps({"f_amount": 5000}))  # ✗

5. get_flow_info 参数是 version_id

问题:"数据不存在"

原因:用 template_id 而非 version_id

解决:

# 先获取 version_id
versions = client.workflow.get_version_list(template_id)
version_id = versions.data[0]["id"]

# 用 version_id 查询
info = client.workflow.get_flow_info(version_id)

6. 审批人不能与发起人相同

问题:报"系统异常"

原因:JNPF 规则不允许用户审批自己发起的流程

解决:使用另一个用户账号审批

7. 前端报 undefined.vue

问题:报 "该文件不存在: ../views/workFlow/workFlowForm/undefined.vue"

排查:

  1. 确认表单已发布(base_visualdev_release 有记录)
  2. 确认 workflow_node 起始节点的 f_form_id 与 base_visual_dev ID 一致
  3. 确认 App-Code 正确

8. create_template 后无法 save_flow

问题:save_flow 报 "数据不存在"

原因:templateJson 实体未创建

解决:使用 create_simple_flow() 或确保 create_template 时传入完整的 flowXml/flowNodes/flowConfig

9. 删除资源顺序

问题:删除时报外键约束错误

正确顺序:

  1. 流程模板
  2. 表单
  3. 功能菜单
  4. 目录菜单
# 1. 先删模板
client.workflow.delete_template(template_id)

# 2. 再删表单
client.visual_dev.delete(func_id)

# 3. 删功能菜单
client.menu.delete(menu_id)

# 4. 最后删目录菜单
client.menu.delete(dir_id)

错误码

错误码 说明
SUCCESS (200) 成功
FAILURE (999) 失败
DEPLOY_ERROR (9001) 部署错误,检查 XML 格式
DEFINITION_NOT_EXIST (9002) 流程模板不存在
INSTANCE_NOT_EXIST (9003) 实例不存在
TASK_NOT_EXIST (9004) 任务不存在
WF081 已完成的任务不能加签
WF106 不能给自己加签/审批

日志位置

日志 路径
错误日志 log/jnpf-java-boot/log_error.log
全量日志 log/jnpf-java-boot/log_total.log
后端源码 jnpf/后端/jnpf-java-boot/jnpf-flowable/

调试建议

  1. API 调试:使用 Swagger http://127.0.0.1:30000/doc.html
  2. 查看日志:优先查看 log_error.log
  3. 参考前端:查看前端 API 调用方式
  4. 检查数据库:确认 workflow_node、template_json 等表数据正确