Files
2026-05-18 09:28:15 +08:00

13 KiB
Raw Permalink Blame History

快速入门

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 导入,否则项目名无法识别:

  1. 下载 HBuilderX:https://www.dcloud.io/hbuilderx.html
  2. 菜单:文件 → 导入 → 从本地项目导入 → 选择 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', ...})

下一步

  • 阅读 平台机制 了解 App-Code、system_id 等核心概念
  • 阅读 API 参考 查看全部可用接口
  • 阅读 扩展开发指南 了解 codedev 模式开发
  • 后端开发需求:立即触发 backend-dev 技能,在 ssw-{app_code}/util/ 下编写业务 Helper