411 lines
13 KiB
Markdown
411 lines
13 KiB
Markdown
# 快速入门
|
||
|
||
> 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 <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:创建功能表单
|
||
|
||
```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 <func_id> <module_name> [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
|