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

428 lines
15 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.
# 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 结构
```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)` 接收:
```ts
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 顶层结构
```ts
{
// 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 之前)
```ts
{
...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 || []`。
```ts
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,不复刻**。