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

10 KiB
Raw Permalink Blame History

平台机制指南

深入理解 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的方式

  1. 从 config.py 直接使用(推荐):配置文件中已预设业务系统的分类ID
  2. 从平台界面查看:数据中心 → 字典管理 → 查看分类编码
  3. 通过 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 默认