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

411 lines
13 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.
# 快速入门
> 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