# 快速入门 > 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) | **移动端字段配置示例:** ```python 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 环境可用。 ```bash # 验证 Python 版本 python3 --version # 需要 Python 3.8+ ``` **运行方式:** ```python # 方式一:直接运行脚本(推荐) 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 密文 ```python # 通过配置创建(推荐,自动从 config.py 读取 app_code) config = JNPFConfig() client = JNPFClient.from_config(config) # ★ 密码必须是 96 字符 AES 密文(从浏览器提取,Python 无法生成正确密文) # 获取方式:node .claude/scripts/extract_encrypted_password.js 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:创建功能表单 ```python 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:发布功能 ```python # 发布功能(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:创建菜单 ```python # 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:管理数据 ```python # 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()`: ```python # 软删除菜单: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` 区分。 ```python # 方式一:自动创建父目录 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。 ```python 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` 一键完成代码生成 + 类名修复 + 菜单挂载: ```bash python3 aibridge/utils/run-codegen.py [menu_title] ``` ## 完整流程总结 ``` 创建客户端 → 登录 → 定义字段 → 构建配置 → 创建功能 → 发布 → 创建菜单 → 数据CRUD → 代码生成 ``` ## 完整标准示例 **`aibridge/examples/quickstart.py`** 是端到端可运行的权威示例,覆盖所有主要操作: ``` 登录 → 创建功能表单 → 发布 → 创建菜单 → 数据 CRUD → 代码生成 → 软删除 → 清理 ``` > **铁律 1**:DI(数据接口)作为临时查询手段,当需要复杂业务逻辑时,立即触发 `backend-dev` 技能,导出模型代码 + 编写业务 Helper。 运行方式: ```bash 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 ```bash # 在 HBuilderX 中 # 菜单:运行 → 运行到浏览器 → Chrome(或按快捷键) # 或者使用命令行(项目需先用 HBuilderX 导入) /Applications/HBuilderX.app/Contents/MacOS/cli launch web --project $ccWorkDir/uniapp ``` ### 3. 移动端测试配置 测试配置文件:`test/playwright.mobile.config.ts` ```bash 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', ...})` ## 下一步 - 阅读 [平台机制](platform-guide.md) 了解 App-Code、system_id 等核心概念 - 阅读 [API 参考](api-reference.md) 查看全部可用接口 - 阅读 [扩展开发指南](codedev/) 了解 codedev 模式开发 - **后端开发需求**:立即触发 `backend-dev` 技能,在 `ssw-{app_code}/util/` 下编写业务 Helper