diff --git a/docs/archive/data/buildformdata-contract.md b/docs/archive/data/buildformdata-contract.md deleted file mode 100644 index 30571ae..0000000 --- a/docs/archive/data/buildformdata-contract.md +++ /dev/null @@ -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 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: '' // ★ 关键 -} -``` - -### 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` + `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,不复刻**。