21 KiB
故障排查
AIBridge 和 JNPF 平台的常见问题及解决方案。
1. 菜单不显示
症状
创建功能并发布后,在业务系统中看不到菜单。
原因
请求未携带正确的 App-Code 请求头。后端默认使用系统平台(systemId = 309228585019769285),导致创建的功能和菜单归属到系统平台。
排查步骤
# 1. 检查客户端是否设置了 app_code(关键!)
print(f"App-Code: {client.app_code}") # 应为你的业务系统编码,如 "ais"
# 2. 检查是否正确加载了配置
# 错误方式:JNPFClient() 不会自动使用 config.py 中的 app_code
client = JNPFClient() # app_code 为空!
print(f"app_code: {client.app_code}") # 输出为空
# 正确方式:使用 from_config
config = JNPFConfig() # app_code="ais" from config.py
client = JNPFClient.from_config(config)
print(f"app_code: {client.app_code}") # 输出 "ais"
# 3. 检查菜单列表
from aibridge.modules.menu import MenuAPI
menu_api = MenuAPI(client)
menu_list = menu_api.get_list()
print(f"菜单数量: {len(menu_list.data or [])}")
# 4. 检查菜单的 systemId
menu_info = menu_api.get_info("your_menu_id")
print(f"systemId: {menu_info.data.get('systemId')}")
解决方案
必须使用 JNPFClient.from_config(config) 而非 JNPFClient():
from aibridge import JNPFClient, JNPFConfig
# 正确:从 config.py 加载完整配置(包含 app_code)
config = JNPFConfig() # config.py 中已设置 app_code="ais"
client = JNPFClient.from_config(config)
# 错误:直接创建 JNPFClient,app_code 为空
client = JNPFClient() # app_code = "",会登录到平台系统!
验证菜单归属:
# 登录后查询业务系统菜单
sys_menu = client.menu.get_system_menu()
print(f"业务系统菜单数量: {len(sys_menu.data)}")
for m in sys_menu.data:
print(f" {m.get('fullName')} systemId:{m.get('systemId')}")
注意:
JNPFClient()创建的实例app_code="",所有 API 请求都不会带App-Code请求头- 后端
VisualdevController.create()和ModuleController.create()会自动通过App-Code请求头解析 systemId 并写入数据库- 菜单创建后需确认
systemId是否为业务系统的 ID(如 ais 系统为808341719178283333)- 如发现 systemId 错误,可通过
menu.update({"id": menu_id, "systemId": business_system_id})修正
验证: 退出登录后重新登录,或清除浏览器缓存/localStorage,确认 getUserInfo API 返回的 menuList 包含目标菜单。
2. 功能创建成功但无法使用
症状
功能在后台可以看到,但前端点击菜单报错或无响应。
原因
功能未发布(state=0)。JNPF 的功能需要发布后才能在前端使用。
排查
info = visual_dev.get_info(func_id)
print(f"发布状态: {info.data.get('state')}") # 0=未发布, 1=已发布
解决方案
visual_dev.release(func_id)
3. 数据接口执行失败
症状
调用 DataInterfaceAPI.execute() 时报错。
常见原因及解决方案
3.1 数据接口不存在或 ID 错误
确认 di_id 正确:
from aibridge.modules.data_interface import DataInterfaceAPI
di_api = DataInterfaceAPI(client)
resp = di_api.get_list()
for item in resp.data.get("list", []):
print(f"接口: {item['fullName']} (id={item['id']})")
3.2 数据接口没有 SQL 执行权限
确认数据接口配置了 SQL 类型的数据源,且使用的数据库连接(dbLinkId: "0")有执行权限。
3.3 SQL 语法错误
检查 SQL 语法,特别注意:
- 字符串值用单引号包裹
- ID 值不能有换行或特殊字符
- UPDATE 语句需要 WHERE 条件(避免全表更新)
- SQL 中不能包含
{}空字面量(会被当作参数占位符解析)
3.4 isPostPosition 未设置导致 NPE
后端日志: NullPointerException at handlePostVariate
isPostPosition 默认为 null,后端自动拆箱时 NPE。解决: 创建 payload 中设置 "isPostPosition": 0。
3.5 DI 参数名必须与 SQL 占位符一致
# SQL 中用 {code},paramList 中 field 也必须是 "code"
sql = "SELECT * FROM table WHERE f_code = {code}"
di.execute(di_id, {"code": "ABC"}) # 正确
di.execute(di_id, {"f_code": "ABC"}) # 错误
4. Token 过期
症状
AuthError: [401] 登录已过期
解决方案
# 重新登录(密码必须是 96 字符 AES 密文)
# 获取方式:node .claude/scripts/extract_encrypted_password.js <account> <password> <app_code>
client.login(account="admin", password="d4958348...") # 96字符AES密文
# 或使用已有 token
client.login_by_token("bearer eyJ...")
注意: JNPF 登录返回的 token 已包含
"bearer "前缀,不要重复添加。
5. formData/columnData JSON 格式错误
症状
创建功能成功但发布后前端报错,或表单显示异常。
常见格式问题
ruleList必须是对象:{"matchLogic": "and", "conditionList": []},不能为 nulltabConfig不能为 null:应为{"on": False, "relationField": "", "hasAllTab": True}propertyJson必须是 JSON 字符串(json.dumps({...})),不是 Python dicttables、formData、columnData必须是 JSON 字符串
推荐:使用构建器
from aibridge.builders.full_config import build_full_config, build_create_payload
config = build_full_config(
full_name="测试功能", en_code="testFunc",
table_name="base_test", table_label="测试表",
fields=[...],
)
payload = build_create_payload(config) # formData、columnData、tables 格式已保证正确
6. 删除操作报外键约束错误
症状
删除功能、菜单、流程模板时报错,提示外键约束或"系统异常"。
依赖关系
流程模板 → 引用 → 表单(visual_dev)→ 引用 → 发布记录(visual_release)→ 引用 → 菜单(module)
解决方案:正确的删除顺序
# 1. 先删除流程模板(解除对表单的引用)
for item in client.workflow.get_template_list({"keyword": "xxx"}).data.get("list", []):
client.workflow.delete_template(item["id"])
# 2. 再删除功能菜单(type=3)
for item in client.menu.get_list({"keyword": "xxx"}).data.get("list", []):
if item.get("type") == 3:
client.menu.delete(item["id"])
# 3. 删除表单
for item in client.visual_dev.get_list({"keyword": "xxx"}).data.get("list", []):
client.visual_dev.delete(item["id"])
# 4. 最后删除目录菜单(type=1)
for item in client.menu.get_list({"keyword": "目录名"}).data.get("list", []):
if item.get("type") == 1:
client.menu.delete(item["id"])
菜单删除 NPE 的替代方案
ModuleController.delete() 在子菜单 parentId 为 null 时会 NPE(JNPF 后端 bug)。
替代方案:使用 menu_api.soft_delete() 软删除。
推荐方案:soft_delete 代替 delete
删除后重新创建同名/同编码资源会报"编码/名称不能重复",因为 JNPF 的 delete 可能未彻底清除数据。
# ★ 推荐用 soft_delete:修改属性使其不可见且不冲突
client.menu.soft_delete(menu_id)
# 效果:parentId=-100, enabledMark=0, 名称加ID后缀, enCode=menu_{id}
client.visual_dev.soft_delete(func_id)
# 效果:名称加ID后缀, enCode=func_{id}, sortCode=999999
# 软删除后可以安全地用原编码重新创建
client.menu.create_form_menu(full_name="客户列表", en_code="customerList", ...)
7. 创建功能报"请在数据库中添加对应的数据表"
症状
调用 visual_dev.create() 时报错。
原因
JNPF 的 create 接口在创建时会校验 tables 中引用的物理表是否已存在。
解决方案
方案 A:动态建表(推荐) — 使用 build_create_payload(config)(默认 dynamic_table=True),create 时传空 tables 跳过校验,Release 时自动建表。
方案 B:预建表模式 — 如果物理表已存在,使用 build_create_payload(config, dynamic_table=False)。
8. 流程发起报错 "map is null" 或 formData 无效
症状
POST /api/workflow/task 发起流程报"系统异常"。
原因
流程发起的 formData 字段类型为 Map<String, Object>。如果传入 JSON 字符串(json.dumps(dict)),会被反序列化为 String 而非 Map,导致 NPE。
解决方案
# 正确:formData 直接传 dict
client.workflow.launch_task(version_id, {
"f_order_no": "CG-001",
"f_item_name": "中性笔",
})
# 错误:不要 json.dumps 序列化 formData
发起流程后表单数据为空
如果 launch_task 返回成功,但流程详情中表单数据为空,检查:
- 字段名匹配:确保
formData中的字段名与流程模板中定义的字段完全一致 - 字段名前缀:必须使用小写
f_前缀(如f_order_no) - 字段类型:数字、日期等类型需与表单设计一致
# 正确
form_data = {
"f_order_no": "CG-001", # 小写 f_ 前缀 + snake_case
"f_amount": 1000, # 数字直接传
"f_create_time": "2024-01-01" # 日期字符串
}
# 错误:少了 f_ 前缀
form_data = {
"order_no": "CG-001", # 缺少 f_ 前缀
}
9. 前端发起流程报 "该文件不存在: undefined.vue"
症状
该表单已删除 该文件不存在: ../views/workFlow/workFlowForm/undefined.vue
错误链
前端 FlowParser.vue → getFlowTaskInfo
→ 后端 workflow_node 获取起始节点 formId
→ visualdevApi.getFormConfig(formId) 查 base_visualdev_release
→ 返回 null 或 enCode 为空 → formInfo.enCode = undefined
根因排查顺序
- 前端 URL 是否包含正确的 app 前缀(如
/wj/),否则 systemId 解析为默认平台值 - workflow_node 表中起始节点的
f_form_id是否与base_visual_dev表 ID 一致 - base_visualdev 和 workflow_template 的
f_system_id是否一致(多租户隔离) - 表单是否已发布(
base_visualdev_release表是否有对应记录) - 流程模板是否已启用(
enabledMark = 1)
诊断工具
python3 -m aibridge.examples.diagnose_workflow_form
10. 创建流程模板后 save_flow 报 "数据不存在"
症状
POST /api/workflow/template/Save 返回 "数据不存在"。
原因
创建模板时未传 flowXml/flowNodes/flowConfig,导致后端 NPE,templateJson 未创建。
解决方案
# 推荐使用便捷方法
result = client.workflow.create_simple_flow(
full_name="审批流程", en_code="approvalFlow",
form_id=form_id, approver_user_ids=["user_id"], form_name="表单名称",
)
11. get_flow_info 返回 "数据不存在"
症状
GET /api/workflow/template/Info/{id} 返回 "数据不存在"。
原因
Info/{id} 端点查的是 version_id(flowId),不是 template_id。
解决方案
versions = client.workflow.get_version_list(template_id)
flow_id = versions.data[0]["id"]
info = client.workflow.get_flow_info(flow_id) # 用 version_id
12. relationForm 弹出窗口报错或显示空白
症状 A:弹出窗口报 "Cannot read properties of undefined (reading 'includes')"
columnOptions items 缺少 value 字段(应等于数据库字段名)。
症状 B:表单设计器列表字段显示空白
columnData.columnOptions items 缺少顶层 prop 字段(应等于 __vModel__)。
排查
resp = client.visual_dev.get_info(form_id)
form_data = json.loads(resp.data["formData"])
col_data = json.loads(resp.data["columnData"])
for field in form_data["fields"]:
if field.get("__vModel__") == "f_xxx":
for col in field.get("columnOptions", []):
print(f"value={col.get('value')}, prop={col.get('prop')}")
解决方案
修复已有表单 — 从目标表单获取 columnOptions,确保每个 item 有 value 和 prop 字段后写回。
两阶段创建(推荐) — 先创建被引用表单(得到 form_id),再创建带 relationForm 的表单(设置 modelId)。参考 aibridge/examples/create_image_management.py。
13. select 字段下拉选项不显示
症状
下拉框点击后有选项,但选项文字为空。
正确的字段配置
{
"options": [
{"fullName": "正常", "id": "normal"},
{"fullName": "损坏", "id": "corrupted"}
],
"props": {
"label": "fullName",
"value": "id",
"children": ""
},
"__config__": {
"jnpfKey": "select",
"options": null
}
}
关键点:
options格式是{fullName, id},不是{label, value}props.label必须指向"fullName",props.value指向"id"- select 字段必须配置
props,否则后端报PropsModel.getLabel() is null
选项来源方式
方式一:静态 options — 在 FieldDef 中配置 options 列表。
方式二:关联数据字典 — 设置 __config__.dataType = "dictionary" 和 __config__.dictionaryType = dict_type_id。
14. 创建表单/菜单报"编码/名称不能重复"
症状
删除表单或菜单后,用相同 enCode/fullName 重新创建时报重复错误。
原因
JNPF 的 enCode/fullName/urlAddress 在全系统范围唯一校验,包括已软删除的记录。
解决方案 A:soft_delete(推荐)
# ★ 用 soft_delete 代替 delete,自动释放编码
client.menu.soft_delete(menu_id) # enCode → menu_{id}
client.visual_dev.soft_delete(func_id) # enCode → func_{id}
# 软删除后,`create_form_menu` / `create_page_menu` 会自动用临时名称创建再 rename
# 无需额外处理
client.menu.create_form_menu(full_name="客户列表", en_code="customerList", ...)
解决方案 B:创建前检查 + 唯一编码
# 创建前检查
if client.visual_dev.check_en_code_exists("equipmentCategory"):
existing_id = client.visual_dev.get_id_by_en_code("equipmentCategory")
# 使用时间戳生成唯一编码
import time
unique_code = f"eqCategory{int(time.time() * 1000) % 1000000}"
15. 创建菜单成功但 id 为 None
原因
JNPF Menu API 返回 {"code":200,"msg":"新建成功"} 但不包含 data.id,需通过 get_id_by_en_code 查询。
解决方案
create_form_menu / create_page_menu 已内置自动查询,resp.id 直接返回实际 ID:
resp = client.menu.create_form_menu(full_name="客户列表", en_code="customerList", ...)
print(f"菜单ID: {resp.id}") # ✅ 直接返回实际 ID,无需二次查询
所有 create_* 方法已内置 id=null 自动修复。
16. DI Preview 执行 SQL 查不到数据(多租户隔离)
症状
通过 DI Preview 执行 SELECT 返回空,但 List API 能看到数据。
原因
- List/CRUD API:通过 MyBatis-Plus 操作,自动添加租户过滤,连接租户库
- DI Preview:通过
dbLinkId指定的数据库连接直接执行 SQL,dbLinkId=0连接的是主库
可通过 DI Preview 访问的表(主库)
base_visual_dev、base_visual_release 及动态建表的业务表。
租户库中的表(如 base_data_interface)需通过标准 API(如 visual_dev.create_data())操作。
排查流程
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | 确认 DI 的 dbLinkId 参数 |
非 0 表示业务库 |
| 2 | 确认表所在数据库 | 主库 vs 租户库 |
| 3 | 确认 SQL 语法正确 | 可以直接执行 |
| 4 | 通过 List API 验证 | API 能查到说明数据存在 |
提示:如果 DI Preview 查不到但 List API 能查到,说明表在租户库,需要用
dbLinkId指定对应数据源。
17. 连接失败 / 其他环境问题
连接失败
client = JNPFClient(
base_url="http://localhost:30000",
verify_ssl=False, # 跳过 SSL 验证
timeout=30, # 增加超时时间
)
f_delete_mark 为 NULL
通过 SQL 直接 INSERT 时,确保 f_delete_mark = 0(正常)或 1(已删除),不能为 NULL。
自己发起的流程自己无法审批
JNPF 规则:发起人不能同时是同节点的审批人。测试时使用两个不同用户。
测试步骤:
- 用户 A(发起人)登录 → 发起流程
- 用户 B(审批人)登录 → 待审核列表能看到 → 审批通过
- 用户 A 无法在自己的待审核列表中看到自己发起的任务
如果需要自己审批:可以在流程设计中将审批人设为"发起人自审",或设置会签/或签模式。
批量操作性能
逐个处理时增加 time.sleep(0.3) 间隔避免服务端限流。
18. relationForm 字段选择后无反应或列表为空
症状
- 弹出窗口报错或显示空白
- 列表只显示序号,不显示名称
- 选择后确定按钮无反应
根因
relationForm 需要 4 个关键配置:
| 配置 | 说明 | 正确值 | 错误值 |
|---|---|---|---|
modelId |
目标表单 ID | 被关联表单的 visual_dev ID | 空或错误 ID |
relationField |
显示文本字段 | f_name(小写,表单字段定义中的字段名) |
f_id |
propsValue |
存储值字段 | f_id(小写,JNPF DataChange API 返回的主键是小写) |
F_Id(大写) |
columnOptions |
弹窗列表列配置 | [{value: "f_name", label: "名称"}],从目标表单 columnData 提取 |
空 |
关键:
propsValue必须用小写f_id,因为 JNPF 内部 DataChange API 返回的 JSON 主键是f_id(小写),即使数据库列是F_Id(大写)。
解决方案:两阶段创建 + 后处理
第一阶段:创建被引用的表单(目标表单),获取其 ID。
第二阶段:创建带 relationForm 的表单时,通过 FieldDef.relation_config 声明配置:
fields = [
# ... 其他字段 ...
FieldDef(field="f_project_id", field_name="所属项目",
jnpf_key="relationForm",
relation_config={
"modelId": "目标表单ID", # 被关联的表单ID
"relationField": "f_name", # 显示文本字段(小写)
"propsValue": "f_id", # 存储值(小写,不是 F_Id)
"popupTitle": "选择项目",
}),
]
第三阶段(发布后必须):从目标表单提取 columnOptions 并更新字段,然后重新发布:
import json
def fix_relation_form(client, form_id, target_form_id):
"""relationForm 后处理:从目标表单提取 columnOptions"""
# 1. 获取目标表单的列配置
resp = client.request('GET', f'/api/visualdev/Base/{target_form_id}')
proj_col = json.loads(resp.data.get('columnData', '{}'))
col_opts = [
{"value": f.get('__vModel__'), "label": f.get('__config__', {}).get('label')}
for f in proj_col.get('columnOptions', [])
if f.get('__vModel__') and f.get('__config__', {}).get('label')
]
# 2. 更新当前表单的 relationForm 字段
form_resp = client.request('GET', f'/api/visualdev/Base/{form_id}')
form_data = json.loads(form_resp.data.get('formData', '{}'))
for f in form_data.get('fields', []):
if f.get('__config__', {}).get('jnpfKey') == 'relationForm':
f['columnOptions'] = col_opts
upd = dict(form_resp.data)
upd['formData'] = json.dumps(form_data, ensure_ascii=False)
upd.pop('id', None)
r = client.request('PUT', f'/api/visualdev/Base/{form_id}', data=upd)
if r.code == 200:
client.visual_dev.release(form_id)
return r.code == 200
# 发布后调用
if fix_relation_form(client, func_id, "目标表单ID"):
print("relationForm columnOptions 修复并重新发布成功")
注意:由于目标表单需要先创建才能知道其 ID,
columnOptions无法在build_full_config阶段自动生成。必须在表单发布后,通过查询目标表单的columnData提取,然后更新并重新发布。
完整示例
参考 aibridge/examples/deploy_all.py 中 AisProjectUser 的定义(包含 relationForm 配置)。
调试方法论
核心原则:JNPF 是人工配置为主的低代码平台,当遇到 API 走不通的问题时,应优先参考前端 API 调用及代码实现,并尽快查看后端日志和源码。
排查顺序
1. 前端代码 — 参考前端如何调用 API(请求格式、参数、请求头)
web/
重点: api/ 目录、stores/ 中的状态管理
2. Swagger 文档 — http://127.0.0.1:30000/doc.html#/home
3. 后端日志 — log/jnpf-java-boot/log_error.log / log_total.log
关键搜索: "错误提示"、"当前执行SQL"、"接口请求失败"
4. 后端源码 — jnpf/后端/jnpf-java-boot/jnpf-system/jnpf-system-biz/
重点: DataInterfaceServiceImpl.java, VisualdevController.java
实用调试命令
# 查看最新的后端错误
tail -50 log/jnpf-java-boot/log_error.log
# 查看最近执行的 SQL
grep "当前执行SQL" log/jnpf-java-boot/log_total.log | tail -10
# 搜索特定错误
grep -A 5 "错误提示" log/jnpf-java-boot/log_total.log | tail -20
Python 调试
import logging
logging.basicConfig(level=logging.DEBUG, format="%(asctime)s [%(name)s] %(levelname)s: %(message)s")
# 检查原始响应
resp = client.request("GET", "/api/system/Menu/ModuleBySystem")
print(f"原始响应: {resp.raw}")
# 快速失败
from aibridge import APIError
try:
resp = client.require_success(client.request("POST", "/api/visualdev/Base", data=payload))
except APIError as e:
print(f"API 错误: code={e.code}, msg={e.msg}, raw={e.raw}")