13 KiB
快速入门
5 分钟完成第一个功能模块的创建、发布、菜单配置和数据管理。
命名规范
| 类型 | 规则 | 示例 |
|---|---|---|
| 数据库表名 | {business_name}(snake_case,无前缀) |
product |
| Java 类名 | {BusinessName}Entity(PascalCase) |
ProductEntity |
注意:
- 业务库已按系统名隔离,表名用 snake_case,不加前缀,不用字符分割
- 平台表(base_*)保持原样,如
base_sales_vendor- Java 类名只使用业务名(PascalCase),不加 app_code 前缀,避免
AisProductEntity这样的重复前缀
配置构建器
AIBridge 提供 6 个配置构建器,覆盖 PC 端和移动端表单配置:
| 构建器 | 用途 |
|---|---|
build_field_model |
PC 单字段模型(25+ jnpfKey 类型) |
build_table_field_model |
PC 子表控件模型 |
build_form_data |
PC 表单布局配置 |
build_column_data |
PC 列表列配置 |
build_full_config |
组装 formData + columnData + tables |
build_mobile_column_data |
移动端列配置(f_app_column_data) |
移动端字段配置示例:
from aibridge.builders.mobile_field_model import build_mobile_column_data
fields = [
{"fieldName": "客户名称", "field": "f_customer_name", "jnpfKey": "input", "required": True},
{"fieldName": "状态", "field": "f_status", "jnpfKey": "select", "options": [{"fullName": "启用", "id": "1"}]},
]
mobile_column = build_mobile_column_data(fields)
# 输出供 f_app_column_data 使用
前置条件
- JNPF 平台已部署并运行(默认地址
http://localhost:30000) - 已有管理员账号和密码
- 已创建业务系统(获取
app_code和system_id) - Python 3.8+
步骤 1:安装与配置
AIBridge 是项目的一部分,无需单独安装。只需确保 Python 3 环境可用。
# 验证 Python 版本
python3 --version # 需要 Python 3.8+
运行方式:
# 方式一:直接运行脚本(推荐)
cd /path/to/project
python3 aibridge/examples/quickstart.py
# 方式二:在代码中使用
import sys
sys.path.insert(0, "/path/to/project") # 确保项目根目录在 sys.path
from aibridge import JNPFClient, JNPFConfig
# 通过配置创建(推荐,自动读取 app_code、密码等)
config = JNPFConfig()
client = JNPFClient.from_config(config)
# 或直接创建
client = JNPFClient(
base_url="http://localhost:30000",
app_code="wj",
timeout=30,
verify_ssl=False,
)
预期输出: 无报错,客户端初始化完成。
步骤 2:登录
铁律 2:前端页面用真实密码,后端 API 必须使用 96 字符 AES 密文
# 通过配置创建(推荐,自动从 config.py 读取 app_code)
config = JNPFConfig()
client = JNPFClient.from_config(config)
# ★ 密码必须是 96 字符 AES 密文(从浏览器提取,Python 无法生成正确密文)
# 获取方式:node .claude/scripts/extract_encrypted_password.js <account> <password> <app_code>
resp = client.login() # 自动使用 CONFIG 中的账号密码
print(f"登录结果: code={resp.code}, msg={resp.msg}")
print(f"Token: {client.token[:20]}...")
# 获取当前用户信息
user_resp = client.get_user_info()
print(f"用户: {user_resp.data.get('userName')}")
预期输出:
登录结果: code=200, msg=操作成功
Token: bearer eyJhbGciOiJIUz...
用户: admin
步骤 3:创建功能表单
from aibridge.builders.full_config import build_full_config, build_create_payload
from aibridge.models import FieldDef
config = JNPFConfig()
# 使用 FieldDef 定义业务字段(推荐,自动补全默认值)
fields = [
FieldDef(field="f_name", field_name="名称", required=True),
FieldDef(field="f_code", field_name="编码", required=True),
FieldDef(field="f_type", field_name="类型", jnpf_key="select", options=[
{"fullName": "电子产品", "id": "1"},
{"fullName": "办公用品", "id": "2"},
]),
FieldDef(field="f_price", field_name="单价", jnpf_key="inputNumber",
data_type="decimal", data_length="18,2"),
FieldDef(field="f_description", field_name="描述"),
]
# 构建完整配置
full_cfg = build_full_config(
full_name="产品管理",
en_code="productManage",
table_name="product", # ★ 纯业务名 snake_case,不加前缀
table_label="产品表",
description="产品信息管理",
category=config.business_category_id, # 功能表单分类ID(从config.py读取)
fields=[f.to_dict() for f in fields],
web_type=2, # 2=表单加列表
)
# 创建功能(dynamic_table=True 时跳过物理表校验,Release时自动建表)
payload = build_create_payload(full_cfg, dynamic_table=True)
resp = client.visual_dev.create(payload)
if not resp.success:
print(f"创建失败: {resp.msg}")
exit(1)
func_id = resp.id
# API 有时返回 id=null,需二次查询
if not func_id:
func_id = client.visual_dev.get_id_by_en_code("productManage")
print(f"功能创建成功,ID: {func_id}")
预期输出:
功能创建成功,ID: 4234567890123456789
步骤 4:发布功能
# 发布功能(systemId 在创建时已由 App-Code 自动设置,发布时继承)
release_resp = client.visual_dev.release(func_id)
print(f"发布结果: code={release_resp.code}, msg={release_resp.msg}")
预期输出:
发布结果: code=200, msg=操作成功
visual_dev: 200 操作成功
visual_release: 200 操作成功
module: 200 操作成功
步骤 5:创建菜单
# 5.1 创建目录菜单(type=1)
dir_resp = client.menu.create_directory_menu(
full_name="产品中心",
en_code="product_dir",
icon="icon-ym icon-ym-folder",
sort_code=100,
parent_id="-1", # 顶级目录
)
print(f"目录菜单创建成功,ID: {dir_resp.id}")
# 5.2 创建功能菜单(type=3),挂在目录下
menu_resp = client.menu.create_form_menu(
full_name="产品列表",
en_code="productList",
visual_dev_id=func_id,
parent_id=dir_resp.id or "-1",
sort_code=1,
)
print(f"功能菜单创建成功,ID: {menu_resp.id}")
说明:
create_form_menu已内置自动处理 fullName 唯一性冲突和 ID 查询,menu_resp.id直接返回实际菜单 ID。
步骤 6:管理数据
# 6.1 新增数据
create_resp = client.visual_dev.create_model(func_id, {
"f_name": "蓝牙耳机",
"f_code": "BT-001",
"f_type": "电子产品",
"f_price": 299.00,
"f_description": "高品质无线蓝牙耳机",
})
print(f"新增: code={create_resp.code}, id={create_resp.id}")
# 6.2 查询列表
list_resp = client.visual_dev.get_model_list(func_id, {
"currentPage": 1,
"pageSize": 20,
})
records = list_resp.data.get('list', [])
print(f"查询: 共 {len(records)} 条记录")
for r in records:
print(f" - {r.get('f_name')} ({r.get('f_code')})")
# 6.3 获取详情
if records:
record_id = records[0].get("F_Id") or records[0].get("id")
detail_resp = client.visual_dev.get_model_info(func_id, record_id)
print(f"详情: {detail_resp.data.get('f_name')}")
# 6.4 更新数据
if records:
update_data = records[0].copy()
update_data["f_price"] = 259.00
update_resp = client.visual_dev.update_model(func_id, update_data)
print(f"更新: code={update_resp.code}")
# 6.5 删除数据
if records:
record_id = records[0].get("F_Id") or records[0].get("id")
delete_resp = client.visual_dev.delete_model(func_id, record_id)
print(f"删除: code={delete_resp.code}")
步骤 7:软删除(推荐代替 delete)
JNPF 的 delete() 可能未彻底清除数据,导致重新创建时 enCode 冲突。推荐使用 soft_delete():
# 软删除菜单:parentId=-100、停用、改名改编码
client.menu.soft_delete(menu_id)
# 效果:enCode → menu_{id},原编码自动释放
# 软删除功能表单:改名改编码、sortCode沉底
client.visual_dev.soft_delete(func_id)
# 效果:enCode → func_{id},原编码自动释放
# 软删除后可以安全地用原编码重新创建
步骤 8:创建移动端菜单(可选)
移动端菜单与 Web 端菜单分开管理,使用 category=App 区分。
# 方式一:自动创建父目录
result = client.menu.create_app_form_menu_with_parent(
full_name="数据源管理", # 菜单名称
en_code="menu1775466782807_source", # Web端菜单编码
form_id="810886416123826501", # 表单ID
parent_name="数据管理", # 父目录名称(不存在则自动创建)
parent_en_code="data_manager", # 父目录编码
)
print(f"父目录ID: {result['parent_id']}, 菜单ID: {result['menu_id']}")
# 方式二:手动创建父目录后创建菜单
parent_resp = client.menu.create_app_directory_menu(
full_name="数据管理",
en_code="data_manager",
)
parent_id = parent_resp.id
client.menu.create_app_form_menu(
full_name="数据源管理",
en_code="menu1775466782807_source", # 自动追加 _app 后缀
form_id="810886416123826501",
parent_id=parent_id,
)
说明:移动端菜单的
urlAddress格式为/pages/apply/dynamicModel/index?id={form_id},propertyJson中的moduleId指向对应的表单 ID。
步骤 9:代码生成(含命名修复)
使用
CodeGenerator将已发布的功能表单导出为前后端代码,并自动修复 JNPF 类名前缀 bug。
from aibridge.utils.code_generator import CodeGenerator
gen = CodeGenerator(client, config)
# 1. 生成代码(module_name 使用纯业务名 PascalCase)
result = gen.generate(
func_id=func_id,
module_name="Product", # 生成 ProductEntity,不加 Ais_ 前缀
enable_flow=0,
tables='0',
form_type='2',
description="产品管理",
)
print(f"前端: {result['frontend_path']}")
print(f"后端: {result['backend_path']}")
# 2. 自动修复类名前缀(old_prefix 从 formData 自动计算)
fix_result = gen.fix_class_names(
result['backend_path'], None, "Product", result['frontend_path']
)
for old, new in fix_result['backend']:
print(f" {old} → {new}")
JNPF 命名 Bug:JNPF CodeGenerator 生成
Ais_aisprojectEntity而不是ProjectEntity。fix_class_names()自动将Ais_aisproject*修复为Project*,同时修复 Controller API 路径和前端 api.ts。
便捷脚本:aibridge/utils/run-codegen.py 一键完成代码生成 + 类名修复 + 菜单挂载:
python3 aibridge/utils/run-codegen.py <func_id> <module_name> [menu_title]
完整流程总结
创建客户端 → 登录 → 定义字段 → 构建配置 → 创建功能 → 发布 → 创建菜单 → 数据CRUD → 代码生成
完整标准示例
aibridge/examples/quickstart.py 是端到端可运行的权威示例,覆盖所有主要操作:
登录 → 创建功能表单 → 发布 → 创建菜单 → 数据 CRUD → 代码生成 → 软删除 → 清理
铁律 1:DI(数据接口)作为临时查询手段,当需要复杂业务逻辑时,立即触发
backend-dev技能,导出模型代码 + 编写业务 Helper。
运行方式:
cd /path/to/project
python3 aibridge/examples/quickstart.py
该示例包含完整的错误处理(id=None fallback、清理残留数据等),遇到问题时以此文件为准。
移动端 H5 开发与测试
1. 项目导入(必须用 HBuilderX)
移动端项目必须通过 HBuilderX 导入,否则项目名无法识别:
- 下载 HBuilderX:https://www.dcloud.io/hbuilderx.html
- 菜单:文件 → 导入 → 从本地项目导入 → 选择
uniapp/(基于 jnpf/移动端/jnpf-app-vue3 复制)
2. 运行移动端 H5
# 在 HBuilderX 中
# 菜单:运行 → 运行到浏览器 → Chrome(或按快捷键)
# 或者使用命令行(项目需先用 HBuilderX 导入)
/Applications/HBuilderX.app/Contents/MacOS/cli launch web --project $ccWorkDir/uniapp
3. 移动端测试配置
测试配置文件:test/playwright.mobile.config.ts
cd $ccWorkDir/test
npx playwright test mobile --reporter=line
4. 移动端 API 地址
| 环境 | 地址 |
|---|---|
| 后端 API | http://localhost:30000 |
| 移动端 H5 | http://127.0.0.1:3800 |
| PC 端 | http://localhost:3000 |
5. 常见问题
- "功能表单未发布移动端":需要为表单创建 App 端菜单,参见步骤8
- App 端菜单查询:
client.menu.get_list({'category': 'App', ...})