# 平台机制指南 > 深入理解 JNPF 低代码平台的核心运行机制,避免开发中的常见陷阱。 ## App-Code 多应用机制 JNPF 支持多业务系统(多应用)部署在同一平台实例中。每个业务系统通过 **App-Code** 进行识别。 ### 请求链路 ``` 用户访问 URL 前缀(如 /wj/) → 前端设置 App-Code 请求头("wj") → 后端根据 App-Code 查找 base_system 表 → 获取 systemId → 按此 systemId 过滤菜单、功能等数据 ``` ### 配置方式 ```python # 创建客户端时指定 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 功能 | ### 创建示例 ```python 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` 包含关键绑定信息: ```json { "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。 详见 [数据接口文档](../datainterface/README.md)。 ## 数据模型约定 ### 系统字段 每个业务表自动包含以下系统字段,由后端 `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: ```python 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 查询**: ```python # 获取功能列表并查看分类 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` 确定连接哪个数据库: ```python # 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。 ### 如何确认表在哪个库 ```python # 创建临时 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 认证机制 ### 登录 ```python # 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 会自动处理前缀: ```python # 如果 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` | 默认 |