Files
dacli/data/buildformdata-contract.md
T
ssw bb3ebafe4d verify: buildFormData import + direct AI 调用验证脚本
- 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)
2026-06-25 11:16:12 +08:00

15 KiB
Raw Permalink Blame History

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 只需要:

  1. 拼 aiModelList(轻量 JSON 包装)
  2. 调后端 buildFormData
  3. 调 create
  4. 调 release
  5. 调 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,不复刻。