314 lines
10 KiB
Markdown
314 lines
10 KiB
Markdown
# 平台机制指南
|
||
|
||
> 深入理解 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` | 默认 |
|