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

720 lines
21 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.
# 故障排查
> 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 <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 字符串
### 推荐:使用构建器
```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<String, Object>`。如果传入 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}")
```