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

173 lines
4.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 故障排查
> 来源:workflow-guide.md 踩坑记录、后端源码分析、工作流开发实践
## 常见错误
### 1. create_template 必须包含 flowXml/flowNodes/flowConfig
**问题**:调用 `create_template` 后报 "数据不存在"
**原因**:`create_template` 内部调用 `flowUtil.create()`,如果 `flowNodes` 为 null,会导致 NPE,`templateJson` 条目未创建
**解决**:使用 `create_simple_flow()` 或确保传入完整参数
```python
# 错误
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
```python
# 正确
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`
```python
# 正确 - 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,不做序列化
```python
# 正确
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
**解决**:
```python
# 先获取 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. 目录菜单
```python
# 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` 等表数据正确