- tests/test-import-buildformdata.ts: 证明 dacli 可 import web 端 buildFormData (替换 #/ alias + @jnpf/utils → uuid.ts + lodash-es → structuredClone) - tests/test-direct-ai-call.ts: 验证直接调 AI API 可用 - tests/test-direct-ai-jnpf-prompt.ts: JNPF 原版 GEN_MODEL_QUETION prompt + Anthropic 格式 + 简单/主子表 2 个测试 - data/buildformdata-contract.md: buildFormData 契约清单(16+50+23 keys) 验证结论: - buildFormData 100% 注入 formId/renderKey/isSubTable (BS-51 根因) - buildFormData 自动为 select/options 注入 (BS-54 根因) - JNPF 原版 prompt 可直接用于直连 AI, 不需 JNPF backend - 后续 _ai.ts 改造为双路径 (env 直连 / JNPF backend fallback)
15 KiB
buildFormData 契约清单(2026-06-25 梳理)
来源:
web/.../FormGenerator/src/helper/formUtils.ts(78 行)+componentMap.ts(2232 行)+config.ts(97 行)+VisualAiServiceImpl.java目的:dacli form 子系统瘦身的依据——只要走 buildFormData,就不需要复刻 schema。
0. 入口(AI 建表 web 端调用链)
用户输入 "做一个客户表"
→ POST /api/visualdev/ai/form body={keyword: "..."}
→ VisualAiServiceImpl.form(keyword)
→ SendAiMessage.generatorModelVO(keyword, aiModel) // 调 Qwen
→ 返回 List<AiFormModel> JSON
→ 后处理(重命名/转换组件)
→ 返回 VisualAiModel { enCode, fullName, aiModelList }
→ web 端 buildFormData(aiModelList) // ★ 关键步骤
→ 返回 { ...defaultDataForm, formData: JSON.stringify(formData) }
→ create(formData) → POST /api/visualdev/Base
→ 落库 base_visual_dev
核心结论:buildFormData 接收 aiModelList(已被后处理),输出完整 formData JSON 字符串。create() 直接吃这个 formData 即可。
1. AI 输入契约(Qwen 收到的 prompt + 输出 schema)
1.1 系统 prompt 摘要(AiConstants.GEN_MODEL_QUETION)
- 让 AI 设计表单结构
- 仅返回 JSON,不解释
- 预期是 JSON 数组(多表单场景)
- 必须规避数据库/编程保留字
- 支持组件列表(25 个 jnpfKey):
- input, textarea, inputNumber, switch, radio, checkbox
- select, datePicker, timePicker
- uploadFile, uploadImg, colorPicker
- rate, slider, editor
- depSelect, posSelect, userSelect, roleSelect, areaSelect
- signature, sign, location
1.2 输出 JSON 结构
[
{
"tableTitle": "商城订单",
"tableName": "online_order_form",
"fields": [
{
"fieldTitle": "订单编号",
"fieldName": "order_id",
"fieldDbType": "varchar",
"fieldComponent": "input",
"fieldOptions": [
{"id": "1", "fullName": "未付款"},
{"id": "2", "fullName": "已付款"}
]
}
]
}
]
2. 后处理规则(VisualAiServiceImpl.getAiFormFieldModels)
在 buildFormData 之前,AI 输出会被强制改写:
| 条件 | 改写动作 |
|---|---|
fieldName 含中文 |
替换为 {fieldComponent}_num{001,002,...} |
fieldName 以 _fk 结尾 |
删除该字段(外键自动生成) |
fieldName 为 null/空 |
同中文,替换为 {fieldComponent}_num{...} |
fieldComponent 不在 25 个 jnpfKey 列表 |
改写为 input |
| 子表 + radio/checkbox | 改写为 select |
| 子表 + textarea/link/button/alert/barcode/qrcode/editor | 改写为 input |
| 第一个 model | 设置 isMain=true, enCode = lowerCamel(tableName) |
| 后续 models | 设置 isMain=false(作为子表) |
含义:AI 输出要"宽容"——buildFormData 不信任 AI,会自己改。但 buildFormData 不会校验列名是否合法(只校验 jnpfKey 是否在 componentList 里)。
3. buildFormData 输入契约
buildFormData(aiModelList) 接收:
type AiFormModel = {
tableTitle: string; // 主表/子表中文名
tableName: string; // 表名(仅主表用于派生 enCode)
isMain: boolean; // 第一个为 true,其余 false
fields: AiFormFieldModel[];
};
type AiFormFieldModel = {
fieldTitle: string; // 字段中文名 → __config__.label
fieldName: string; // 字段名 → __vModel__
fieldComponent: string; // 25 个 jnpfKey 之一 → 查 componentMap
fieldOptions?: {id, fullName}[]; // 仅 dyOptionsList 组件用 → options
};
4. buildFormData 输出契约
4.1 顶层结构
{
// 16 个 defaultDataForm 字段(见 §5)
id: '',
fullName: '',
enCode: '',
type: 1,
webType: 2,
dbLinkId: '0',
sortCode: 0,
state: 1,
category: '',
description: '',
interfaceId: '',
interfaceName: '',
interfaceParam: '',
columnData: null,
appColumnData: null,
tables: '[]',
formData: '<JSON string of FormConf + fields>' // ★ 关键
}
4.2 formData 字段(被 JSON.stringify 之前)
{
...formConf, // 50 个表单属性(见 §6)
fields: [...buildFields(aiModelList)] // 字段数组
}
5. defaultDataForm 字段(16 个)
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id |
string | '' |
主键,新建时为空 |
fullName |
string | '' |
用户必填,表单中文名 |
enCode |
string | '' |
用户必填,英文名(唯一) |
type |
int | 1 |
1=自定义表单, 2=系统表单 |
webType |
int | 2 |
1=仅表单, 2=表单+列表, 4=数据视图 |
dbLinkId |
string | '0' |
'0'=主库, 业务库 ID |
sortCode |
int | 0 |
排序 |
state |
int | 1 |
0=暂存, 1=已发布 |
category |
string | '' |
分类 ID(数据字典) |
description |
string | '' |
描述 |
interfaceId |
string | '' |
关联接口 ID |
interfaceName |
string | '' |
关联接口名 |
interfaceParam |
string | '' |
关联接口参数 |
columnData |
string/null | null |
列表配置(后端另算) |
appColumnData |
string/null | null |
APP 端列表配置 |
tables |
string | '[]' |
关联表 schema(关键!) |
关键洞察:
columnData/appColumnData/tables都是后端二次加工的,不是 buildFormData 构造的- 这解释了 BS-50/BS-51:dacli 自己写 columnData 容易漏
- AI 建表走 buildFormData → 不会有这些问题,因为 buildFormData 不负责这三块
6. formConf(formData 的 50 个表单属性)
| 字段 | 默认值 | 说明 |
|---|---|---|
formRef |
'formRef' |
Vue ref 名 |
formModel |
'dataForm' |
Vue data 名 |
size |
'middle' |
表单尺寸 |
labelPosition |
'right' |
label 位置 |
labelWidth |
100 |
label 宽度 |
labelSuffix |
'' |
label 后缀 |
formRules |
'rules' |
校验规则变量名 |
popupType |
'general' |
弹窗类型 |
generalWidth |
'600px' |
弹窗宽度 |
fullScreenWidth |
'100%' |
全屏宽度 |
drawerWidth |
'600px' |
抽屉宽度 |
gutter |
15 |
栅格间距 |
disabled |
false |
全局禁用 |
span |
24 |
默认栅格 |
colon |
false |
label 冒号 |
hasCancelBtn |
true |
取消按钮 |
cancelButtonText |
'取消' |
取消文字 |
cancelButtonTextI18nCode |
'common.cancelText' |
取消 i18n |
hasConfirmBtn |
true |
确定按钮 |
confirmButtonText |
'确定' |
确定文字 |
confirmButtonTextI18nCode |
'common.okText' |
确定 i18n |
hasConfirmAndAddBtn |
true |
确定并新增 |
hasPrintBtn |
false |
打印按钮 |
printButtonText |
'打印' |
打印文字 |
printButtonTextI18nCode |
'common.printText' |
打印 i18n |
customBtns |
[] |
自定义按钮 |
appCustomBtns |
[] |
APP 端自定义按钮 |
primaryKeyPolicy |
1 |
主键策略 |
concurrencyLock |
false |
乐观锁 |
logicalDelete |
false |
逻辑删除 |
dataLog |
false |
数据日志 |
useBusinessKey |
false |
业务主键 |
businessKeyList |
[] |
业务主键字段 |
businessKeyTip |
'数据已存在,请勿重复提交!' |
业务主键提示 |
printId |
'' |
打印模板 |
formStyle |
'' |
自定义样式 |
classNames |
[] |
自定义类 |
className |
[] |
自定义类(旧) |
classJson |
'' |
自定义类 JSON |
detailExtraList |
[] |
详情页 tab |
funcs |
{onLoad, beforeSubmit, afterSubmit} |
3 个回调函数(JS 代码字符串) |
fields |
[] |
字段数组(被 buildFields 覆盖) |
注意:funcs.onLoad/beforeSubmit/afterSubmit 是 JS 字符串模板,平台升级会改默认实现。dacli 不应自己写。
7. field.config 必填项(23 个 keys)
每个字段的 __config__ 必须包含:
| Key | 必填来源 | 默认值 | 说明 |
|---|---|---|---|
jnpfKey |
componentMap | 来自对应组件 | 唯一组件标识,buildFormData 查找组件用 |
label |
buildFormData | fieldTitle |
中文名 |
tipLabel |
componentMap | '' |
提示标签 |
labelWidth |
componentMap | undefined |
覆盖全局 |
showLabel |
componentMap | true |
是否显示 label |
tag |
componentMap | 'JnpfInput'等 |
Vue 组件 tag 名 |
tagIcon |
componentMap | 'icon-ym icon-ym-...' |
左面板图标 |
tableAlign |
componentMap | 'left' |
列表列对齐 |
tableFixed |
componentMap | 'none' |
列表列固定 |
className |
componentMap | [] |
自定义类 |
defaultValue |
componentMap | 组件特定 | 默认值 |
required |
componentMap | false |
必填 |
layout |
componentMap | 'colFormItem' |
布局 |
span |
componentMap | 24 |
栅格 |
dragDisabled |
componentMap | false |
拖拽禁用 |
visibility |
componentMap | ['pc', 'app'] |
显示端 |
tableName |
componentMap | '' |
子表关联表名 |
noShow |
componentMap | false |
不显示 |
regList |
componentMap | [] |
正则校验 |
trigger |
componentMap | 'blur'/'change' |
校验触发 |
formId |
buildFormData | formItemAi${UUID} |
BS-51 来源:formId 缺失则白屏 |
renderKey |
buildFormData | Date.now() |
BS-51 来源:renderKey 缺失则不刷新 |
isSubTable |
buildFormData | false/true |
是否在子表中 |
子表额外字段:
parentVModel: 子表字段要绑定到父表 tableName
关键洞察:BS-51(config 缺 18 键导致白屏)的根因就是 dacli 自己实现 buildFormData 时漏了 formId/renderKey/isSubTable 这 3 个 buildFormData 注入的字段。
8. 4 类组件清单(componentMap 导出)
8.1 inputComponents(19 个)
- input, textarea, inputNumber, switch, radio, checkbox
- datePicker, timePicker
- uploadFile, uploadImg
- colorPicker, rate, slider, editor
- (注:实际数量需数 componentMap 文件;上面是常见)
8.2 selectComponents(约 12 个)
- organizeSelect, posSelect, userSelect, roleSelect, groupSelect
- table(子表)
- treeSelect
- popupTableSelect
- cascader, depSelect, areaSelect
- popupSelect
8.3 systemComponents(7 个)
- createUser, createTime, modifyUser, modifyTime
- currOrganize, currPosition
- billRule
8.4 ocrComponents(9 个,OcrGenItem 类型)
- textOcr, idCardFrontOcr, idCardBackOcr
- businessLicenseOcr, invoiceOcr
- drivingLicenseOcr, vehicleLicenseOcr
- bankCardOcr, trainTicketOcr
8.5 layoutComponents(7 个,AI 不生成)
- groupTitle, divider, collapse, tab, steps, row, card, tableGrid
buildFormData 不生成 layoutComponents——它只从 inputComponents + selectComponents + systemComponents + ocrComponents 中查找(行 16)。
9. dyOptionsList(5 个组件需要 options 字段)
buildFormData 行 32:仅对 dyOptionsList.includes(jnpfKey) 的组件设置 options = child.fieldOptions || []。
const dyOptionsList = ['radio', 'checkbox', 'select', 'cascader', 'treeSelect'];
这 5 个组件必须有 options 数组(BS-54 根因)。
10. 4 个隐藏约束(dacli 必须知道的)
10.1 字段名约束
- 必须 snake_case
- 必须以
f_开头(fpa 规范,CLAUDE.md §3) - 不能含中文(被后处理重命名)
- 不能以
_fk结尾(被删除) - 不能用
f_version(系统保留字)
10.2 jnpfKey 约束
- 必须是 componentMap 中存在的 key
- 不在 25 个 AI 支持列表 → 改写为
input - sub-table 内的 radio/checkbox → 改写为
select - sub-table 内的 textarea/link/button/alert/barcode/qrcode/editor → 改写为
input
10.3 formId/renderKey 约束(buildFormData 注入)
formId:formItemAi${buildBitUUID()}—— 必填renderKey:Date.now()—— 必填- 这两个字段 buildFormData 会自动注入,dacli 不需要生成
- 但 dacli 如果自己实现 schema,必须生成(这就是 BS-51 的根因)
10.4 父子表 ER 约束
- 主表
isMain=true+enCode = lowerCamel(tableName) - 子表
isMain=false+__vModel__ = tableField${UUID} - 子表字段的
__config__.parentVModel = 主表 tableName - dacli 必须保证子表字段的 parentVModel 与主表 tableName 一致
11. 当前 dacli 复刻了 buildFormData 的什么
| dacli 文件 | 对应 buildFormData 逻辑 | 状态 |
|---|---|---|
dacli/src/services/form/_simplify.ts |
formConf + config 简化版 | ❌ 漏 formId/renderKey/isSubTable |
dacli/src/services/form/_precheck.ts (L1) |
字段名/jnpfKey 校验 | ❌ 不全 |
dacli/src/services/form/_blindspot_guards.ts (L2) |
22 运行时 guard | ⚠️ 是补丁不是根因 |
dacli/src/services/form/client.diagnoseError() (L3) |
错误诊断 | ⚠️ 头痛医头 |
dacli/data/form-type-rules.json |
7+6 type×webType 规则 | ⚠️ 复刻 componentMap |
dacli/scripts/extract-web-schema.py |
提取 componentMap | ❌ 静态快照,会过时 |
dacli form validate |
校验 schema 完整性 | ⚠️ 应该不需要 |
dacli form fixcolumndata |
补 config 18 键 | ❌ 应该不需要 |
所有这些都是「buildFormData 已经被复刻但有遗漏」的体现。
12. 理想架构:dacli form = buildFormData 包装
dacli form create --fields='[...]'
│
▼
调后端 buildFormData (或 ai/form)
│
▼
拿到 formData JSON
│
▼
POST /api/visualdev/Base
│
▼
form ID
dacli 只需要:
- 拼
aiModelList(轻量 JSON 包装) - 调后端 buildFormData
- 调 create
- 调 release
- 调 menu mount
没有 schema 构造逻辑、guard、validate、fix、rules、extract。
13. 待评估:dacli 现有代码清理清单
待确认后清理:
dacli/src/services/form/_simplify.ts(删除或缩到 50 行内)dacli/src/services/form/_precheck.ts(删除)dacli/src/services/form/_blindspot_guards.ts(删除或保留作 fallback)dacli/data/form-type-rules.json(删除)dacli/scripts/extract-web-schema.py(删除)dacli form validate子命令(删除)dacli form fixcolumndata子命令(删除)
保留:
dacli form create/info/list/export/import/release/delete(薄包装)dacli menu(菜单挂载)dacli dm(物理表)dacli apis(API 查)
14. 待办:后端是否需要新端点
当前:/api/visualdev/ai/form 强制走 Qwen(不能传 fields)。
需求:dacli 想直接传 fields(不调 AI),需要新端点:
POST /api/visualdev/Base/buildFromFields- 入参:
List<AiFormFieldModel>+tableTitle+tableName - 内部复用 buildFormData 逻辑(Java 复刻 or 抽到 jnpf-common 共享)
两个选项:
- A:后端用 Java 复刻 buildFormData 逻辑(同 BS-XX 风险)
- B:把 buildFormData 抽到 jnpf-common jar,web 端 + 后端 + dacli 共享
B 是正解。需要评估工作量。
15. 一句话总结
buildFormData 是 web 端把
aiModelList翻译成 JNPF 合法 form schema 的函数。dacli form 当前自己实现了一份"翻译",导致 22 个 BS-XX。正确做法是 dacli 直接调 buildFormData,不复刻。