10 KiB
平台机制指南
深入理解 JNPF 低代码平台的核心运行机制,避免开发中的常见陷阱。
App-Code 多应用机制
JNPF 支持多业务系统(多应用)部署在同一平台实例中。每个业务系统通过 App-Code 进行识别。
请求链路
用户访问 URL 前缀(如 /wj/)
→ 前端设置 App-Code 请求头("wj")
→ 后端根据 App-Code 查找 base_system 表
→ 获取 systemId
→ 按此 systemId 过滤菜单、功能等数据
配置方式
# 创建客户端时指定 app_code
client = JNPFClient(base_url="http://localhost:30000", app_code="wj")
# 登录后所有请求自动携带 App-Code 请求头
client.login(account="admin", password="xxx")
App-Code 不设置的影响
如果不设置 app_code,请求不会携带 App-Code 头,后端默认使用系统平台(systemId = 309228585019769285)。这意味着:
- 创建的功能/菜单会归属到系统平台,业务系统中看不到
- 获取菜单列表时返回的是系统平台菜单,不是业务系统菜单
base_system 表结构
通过数据接口或 SQL 可以查看:
| 字段 | 说明 |
|---|---|
| F_Id | 系统ID(即 systemId) |
| F_EnCode | 系统编码(对应 App-Code) |
| F_FullName | 系统名称 |
| F_DeleteMark | 删除标记(0=正常) |
system_id 自动设置
机制说明
JNPF 后端在以下 API 中自动通过 App-Code 请求头解析并写入 systemId,无需手动修正:
| API | 后端代码位置 | 行为 |
|---|---|---|
POST /api/visualdev/Base(创建表单) |
VisualdevController.java:563 |
entity.setSystemId(getInfoByEnCode(getAppCode()).getId()) |
POST /api/visualdev/Base/{id}/Actions/Release(发布) |
VisualdevController.java:669 |
BeanUtil.copyProperties(visualdevEntity, clone) 继承 |
POST /api/system/Menu(创建菜单) |
ModuleController.java:173 |
moduleCrForm.setSystemId(info.getId()) |
流程:
HTTP 请求头 App-Code: wj
→ RequestContext.getAppCode() = "wj"
→ systemService.getInfoByEnCode("wj")
→ SELECT * FROM base_system WHERE F_EnCode = 'wj'
→ 返回 SystemEntity.id → 作为 systemId 写入
验证方法
使用 aibridge/examples/verify_app_code_systemid.py 脚本可快速验证 App-Code 是否正确写入 systemId。
App-Code 常见错误
| 错误现象 | 原因 | 解决方案 |
|---|---|---|
| 表单/菜单创建到系统平台而非业务系统 | app_code 为空或 JNPFClient.from_config(config) 未使用 |
确保 config.py 中 app_code 正确,使用 from_config() 创建客户端 |
config.py 中 app_code 为空字符串 "" |
配置文件未正确设置 | 检查 config.py 中 app_code: str = "wj" |
| base_url 缺少端口导致连接失败 | 本地开发用 30000 端口 | 确保 base_url="http://127.0.0.1:30000" |
| 不同环境使用不同 app_code | dev/test/prod 环境混淆 | 使用环境变量或 separate config.py |
systemId 为 309228585019769285(系统平台) |
App-Code 未生效 | 检查请求头是否正确设置,参见 verify 脚本 |
菜单类型
JNPF 菜单有三种类型,通过 type 字段区分:
| type | 说明 | URL 地址 | 典型用途 |
|---|---|---|---|
| 1 | 目录菜单 | 空 | 分组导航,类似文件夹 |
| 2 | 页面菜单 | 外部或自定义页面URL | 链接到外部系统 |
| 3 | 功能表单菜单 | model/{enCode} |
绑定 VisualDev 功能 |
创建示例
from aibridge.modules.menu import MenuAPI
menu_api = MenuAPI(client)
# 目录菜单(type=1)
menu_api.create_directory_menu(
full_name="办公用品",
en_code="office_dir",
icon="icon-ym icon-ym-folder",
sort_code=100,
parent_id="-1",
)
# 功能表单菜单(type=3)
menu_api.create_form_menu(
full_name="文具订单",
en_code="stationeryOrder",
visual_dev_id="func_id",
parent_id="parent_dir_id",
web_type=2, # 2=表单加列表
)
propertyJson 说明
功能菜单的 propertyJson 包含关键绑定信息:
{
"iconBackgroundColor": "",
"isTree": 0,
"moduleId": "功能ID(base_visual_dev 的 F_Id)",
"webType": 2
}
VisualDev 发布流程
设计功能(base_visual_dev, state=0)
│
▼ 调用 Release API
发布功能(复制到 base_visual_release, state=1)
│
▼ 生成菜单(base_module)
│
▼ 前端可见(App-Code 自动设置 systemId)
关键点:
- 未发布的功能(
state=0)无法在前端使用 - 发布操作会将
base_visual_dev的数据复制到base_visual_release,并将state设为 1 - 每次发布都是全量覆盖,不是增量
- systemId 由 App-Code 请求头自动设置,创建表单/菜单时无需手动指定
数据接口 SQL 执行
通过 DataInterfaceAPI.execute() 直接调用数据接口的 Preview 端点执行 SQL。
详见 数据接口文档。
数据模型约定
系统字段
每个业务表自动包含以下系统字段,由后端 FlowFormDataUtil.generalInsert 自动管理:
| 字段名 | 说明 | 数据类型 |
|---|---|---|
F_Id |
主键 | varchar(50) |
f_flow_task_id |
流程任务ID | varchar(50) |
f_flow_id |
流程ID | varchar(50) |
f_flow_state |
流程状态 | int(9) |
f_tenant_id |
租户ID | varchar(50) |
F_Sort_Code |
排序码 | varchar(50) |
F_Create_User |
创建者 | varchar(50) |
F_Create_Time |
创建时间 | varchar(50) |
F_Modify_User |
修改者 | varchar(50) |
F_Modify_Time |
修改时间 | varchar(50) |
命名规范
- 主键:
F_Id(大写 F 前缀) - 业务字段:
f_field_name(小写 f 前缀 + snake_case) - 流程字段:
f_flow_*(小写 f 前缀 + 下划线) - 审计字段:
F_Create_*、F_Modify_*(大写 F 前缀 + PascalCase)
关键约束
f_delete_mark字段不能为 NULL,应为 0(正常)或 1(已删除)f_tenant_id在多租户模式下自动填充,单租户可以为空F_Id由后端自动生成(通常为雪花ID),无需手动指定
分类 ID(Category)
VisualDev 功能和扩展接口都需要指定 category(分类ID)。分类在平台中预先创建。
使用 config.py 中的默认分类ID
推荐使用 config.py 中预定义的分类ID:
from aibridge import JNPFConfig
config = JNPFConfig()
# 功能表单分类(用于 VisualDev 功能)
business_category_id = config.business_category_id # 功能表单分类ID
print(f"功能表单分类: {business_category_id}")
# 扩展接口分类(用于 DataInterface)
interface_category_id = config.interface_category_id # 扩展接口分类ID
print(f"扩展接口分类: {interface_category_id}")
获取分类ID的方式
- 从 config.py 直接使用(推荐):配置文件中已预设业务系统的分类ID
- 从平台界面查看:数据中心 → 字典管理 → 查看分类编码
- 通过 API 查询:
# 获取功能列表并查看分类
resp = visual_dev.get_list()
for item in resp.data.get("list", []):
print(f"分类ID: {item.get('category')}")
# 获取数据接口列表并查看分类
resp = di.get_list({"category": "扩展接口分类ID"})
常见分类
常见分类由各业务系统自行定义,没有统一的全局分类。AIBridge 配置文件中的分类ID对应各业务系统的特定分类(示例中的 aistudio 仅供参考)。
多租户与数据库隔离
核心概念
JNPF 支持多租户部署。启用多租户后,数据库访问存在两条路径:
| 访问方式 | 数据库连接 | 租户过滤 | 典型场景 |
|---|---|---|---|
| MyBatis-Plus API(标准 CRUD) | 租户库 | 自动(框架拦截器) | visual_dev.create()、menu.get_list() 等 |
| DI Preview(SQL 直连) | dbLinkId 指定的库 |
无 | DataInterfaceAPI.execute() |
DI Preview 的数据库连接
DI Preview 通过 dbLinkId 确定连接哪个数据库:
# dbLinkId=0 连接主库(默认)
payload = DataInterfaceAPI.build_payload(..., db_link_id="0")
关键差异:
base_data_interface(数据接口配置表)等系统表的数据在租户库中, 通过 MyBatis-Plus API 可以正常 CRUD,但 DI Preview 的 SQL 查不到。base_visual_dev(可视化开发表)等业务表在主库中, DI Preview 可以直接查询。
影响范围
当通过 DI Preview 执行 SQL 时,只能访问主库中的表。如果需要操作租户库数据,应使用标准 API 而非 DI SQL。
如何确认表在哪个库
# 创建临时 DI 执行 COUNT 查询
di = DataInterfaceAPI(client)
test_id = di.create_sql_interface(
"检查", "check", "SELECT COUNT(*) as cnt FROM 目标表",
[], category="xxx", action=3,
)
result = di.execute(test_id, {})
cnt = result[0]["cnt"] if result else 0
di.safe_delete(test_id)
# cnt > 0 表示表在主库中可访问
Token 认证机制
登录
# POST /api/oauth/Login(form-urlencoded 格式)
# ★ 密码必须是 96 字符 AES 密文(从浏览器提取,Python 无法生成正确密文)
resp = client.login(account="admin", password="d4958348...") # 96字符AES密文
# 返回 token: "bearer eyJhbGciOiJIUzI1NiJ9..."
Token 格式
Token 格式为 bearer {jwt},注意 bearer 是小写。AIBridge 会自动处理前缀:
# 如果 token 已有 "bearer " 前缀,直接使用
client.login_by_token("bearer eyJ...")
# 如果没有前缀,自动添加
client.login_by_token("eyJ...") # 会自动变为 "bearer eyJ..."
Token 生命周期
- Token 存储在
client.token属性中 - 每次请求自动携带
Authorization请求头 - Token 过期后需要重新登录
请求头约定
AIBridge 发出的请求头(与前端 request.ts 对齐):
| 头 | 值 | 说明 |
|---|---|---|
Authorization |
bearer eyJ... |
认证令牌(小写 bearer) |
App-Code |
wj |
多应用识别码 |
Jnpf-Origin |
pc |
来源标识 |
Vue-Version |
3 |
Vue 版本标识 |
Content-Type |
application/json |
默认 |