auto(bfc0cfa2c3a4): session end @ 2026-07-20T08:58:21 (+1f)
This commit is contained in:
1 parent
5a8cbca732
commit
ec10f7ddfc
1 file changed
-427
@@ -1,427 +0,0 @@
|
||||
# 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,不复刻**。
|
||||
Reference in new issue
Block a user