# 故障排查 > AIBridge 和 JNPF 平台的常见问题及解决方案。 ## 1. 菜单不显示 ### 症状 创建功能并发布后,在业务系统中看不到菜单。 ### 原因 请求未携带正确的 `App-Code` 请求头。后端默认使用系统平台(`systemId = 309228585019769285`),导致创建的功能和菜单归属到系统平台。 ### 排查步骤 ```python # 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()`**: ```python 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 = "",会登录到平台系统! ``` **验证菜单归属:** ```python # 登录后查询业务系统菜单 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 的功能需要发布后才能在前端使用。 ### 排查 ```python info = visual_dev.get_info(func_id) print(f"发布状态: {info.data.get('state')}") # 0=未发布, 1=已发布 ``` ### 解决方案 ```python visual_dev.release(func_id) ``` --- ## 3. 数据接口执行失败 ### 症状 调用 `DataInterfaceAPI.execute()` 时报错。 ### 常见原因及解决方案 **3.1 数据接口不存在或 ID 错误** 确认 `di_id` 正确: ```python 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 占位符一致** ```python # 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] 登录已过期 ``` ### 解决方案 ```python # 重新登录(密码必须是 96 字符 AES 密文) # 获取方式:node .claude/scripts/extract_encrypted_password.js 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 字符串 ### 推荐:使用构建器 ```python 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) ``` ### 解决方案:正确的删除顺序 ```python # 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 可能未彻底清除数据。 ```python # ★ 推荐用 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`。如果传入 JSON 字符串(`json.dumps(dict)`),会被反序列化为 String 而非 Map,导致 NPE。 ### 解决方案 ```python # 正确: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. **字段类型**:数字、日期等类型需与表单设计一致 ```python # 正确 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`) ### 诊断工具 ```bash python3 -m aibridge.examples.diagnose_workflow_form ``` --- ## 10. 创建流程模板后 save_flow 报 "数据不存在" ### 症状 `POST /api/workflow/template/Save` 返回 "数据不存在"。 ### 原因 创建模板时未传 `flowXml/flowNodes/flowConfig`,导致后端 NPE,`templateJson` 未创建。 ### 解决方案 ```python # 推荐使用便捷方法 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。 ### 解决方案 ```python 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__`)。 ### 排查 ```python 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 字段下拉选项不显示 ### 症状 下拉框点击后有选项,但选项文字为空。 ### 正确的字段配置 ```json { "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(推荐) ```python # ★ 用 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:创建前检查 + 唯一编码 ```python # 创建前检查 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: ```python 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. 连接失败 / 其他环境问题 ### 连接失败 ```python 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` 声明配置: ```python 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` 并更新字段,然后重新发布: ```python 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 ``` ### 实用调试命令 ```bash # 查看最新的后端错误 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 调试 ```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}") ```