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

314 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 平台机制指南
> 深入理解 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` | 默认 |