720 lines
21 KiB
Markdown
720 lines
21 KiB
Markdown
# 故障排查
|
||
|
||
> 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}")
|
||
```
|