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

21 KiB
Raw Blame History

故障排查

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": []},不能为 null
  • tabConfig 不能为 null:应为 {"on": False, "relationField": "", "hasAllTab": True}
  • propertyJson 必须是 JSON 字符串(json.dumps({...})),不是 Python dict
  • tables、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 返回成功,但流程详情中表单数据为空,检查:

  1. 字段名匹配:确保 formData 中的字段名与流程模板中定义的字段完全一致
  2. 字段名前缀:必须使用小写 f_ 前缀(如 f_order_no)
  3. 字段类型:数字、日期等类型需与表单设计一致
# 正确
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

根因排查顺序

  1. 前端 URL 是否包含正确的 app 前缀(如 /wj/),否则 systemId 解析为默认平台值
  2. workflow_node 表中起始节点的 f_form_id 是否与 base_visual_dev 表 ID 一致
  3. base_visualdev 和 workflow_template 的 f_system_id 是否一致(多租户隔离)
  4. 表单是否已发布(base_visualdev_release 表是否有对应记录)
  5. 流程模板是否已启用(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 规则:发起人不能同时是同节点的审批人。测试时使用两个不同用户。

测试步骤:

  1. 用户 A(发起人)登录 → 发起流程
  2. 用户 B(审批人)登录 → 待审核列表能看到 → 审批通过
  3. 用户 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}")