低代码对象设计器字段同步与交互修复

status: done created: 2026-06-13 scope: forge-admin-ui, forge-server/forge-framework/forge-plugin-parent/forge-plugin-generator related: code-copilot/changes/form-first-business-object-designer/spec.md

1. 背景

低代码应用构建的业务对象设计器已经采用表单优先模式，表单画布负责生成字段资产，字段资产负责高级维护。当前实际使用中存在以下影响设计效率和运行态一致性的问题：

表单设计器新增字段时，“组件字段ID”只能从已有字段中选择，不能直接输入新字段 ID，导致用户无法在拖入组件时明确字段编码。
表单设计与字段资产的双向同步不完整：表单新增字段要沉淀为字段资产，字段资产改名或改字段编码后也应同步回表单设计器的绑定与展示。
切换左侧导航时经常提示未保存，即使用户没有做业务修改，说明初始化、预览补水或内部同步触发了错误的 dirty 状态。
字段配置当前使用右侧抽屉弹层，编辑字段时遮挡上下文，且频繁开关影响效率。
表单设计器新增字段并同步 DDL 后，数据库列已经存在，但运行态新增/编辑数据时该字段值没有入库。
曾经拖入后又删除的自动字段仍残留在模型字段中，发布检查继续提示追加已不在表单中的字段列。
新版画布“显示名称”清空后会立刻被规范化逻辑自动回填，用户不能一次删除完整名称。

2. 目标

表单设计器中的“组件字段ID”支持选择已有字段，也支持手动输入新字段 ID。
手动输入的新字段 ID 在保存/同步设计草稿时自动沉淀到字段资产，字段名称、列名、类型、组件属性沿用现有自动字段资产规则。
字段资产保存后同步更新本地模型、表单 Schema、页面 Schema 和视图 Schema 中的字段引用；服务端保存后的重载仍作为最终一致性来源。
表单设计器仅在真实 schema/page/field 变更时上报 dirty，初始化、setRule、预览选项补水不触发未保存提示。
字段资产页改为列表 + 右侧内嵌属性面板，不再打开 Naive UI Drawer。
运行态新增/编辑数据时，设计器刚保存且已建表列的新字段能够被动态 CRUD 正常写入。
表单删除自动创建字段后，该字段不再参与模型 Schema、DDL 预览和运行态写入。
字段显示名称允许临时清空，保存前不因内部规范化立刻回填。
必填字段的数据库非空约束只在配置了可用默认值时同步，避免无默认值必填字段阻断运行态新增。

3. 非目标

不修改后端字段设计器接口协议。
不重写 fcDesigner。
不重写发布链路和运行态 AiCrudPage；动态 CRUD 仅修正新增字段写入白名单。
不新增数据库迁移脚本。
不处理字段编码变更后的历史数据迁移策略，仍沿用当前后端字段设计服务的处理。

4. 设计方案

4.1 字段 ID 输入

forgeBusinessComponents.js 中的字段绑定属性规则继续使用 select 类型，但开启可创建输入能力。用户可以：

从已有字段资产中选择字段 ID。
直接输入新字段 ID。

formCreateToForge.js 已经会从 rule.props.fieldBinding.fieldCode、rule.props.fieldCode、rule.field、rule.name 中解析字段编码；本变更保持该转换链路，只补齐属性规则的输入能力。

4.2 双向同步

表单到字段资产：

BusinessFormDesigner.syncDesignerDraft() 继续通过 buildAutoFieldAssets() 从 FormDesignerSchema 自动生成字段资产。
手动输入字段 ID 后，组件 fieldBinding.fieldCode 作为稳定字段编码，自动生成字段资产。

字段资产到表单：

字段资产保存时，如果字段编码发生变化，前端在本地同步替换表单 Schema、页面 Schema、视图 Schema 的引用。
字段名称、提示文案、必填、控件类型等仍由现有字段保存和设计器重载兜底同步。

4.3 Dirty 状态

BusinessFormCreateDesigner.flushDesigner() 增加结构比较：

转换出的 Forge Schema 与当前 modelValue 等价时，只刷新内部快照，不触发 update:modelValue 和 dirtyChange(true)。
仅用户真实拖拽、删除、排序、改字段绑定或修改属性后才上报 dirty。

BusinessFormDesigner.syncDesignerDraft() 增加比较：

当前表单 Schema、字段资产和页面 Schema 均未变化时返回 dirty: false。
左侧导航切换只同步草稿，不制造未保存状态。

4.4 字段配置交互

BusinessFieldManager.vue 去掉抽屉，改为内嵌工作区：

左侧保持字段列表和筛选工具栏。
右侧固定展示 BusinessFieldPropertyPanel。
未选中字段时在右侧展示空状态。
小屏幕下列表与属性面板纵向堆叠。

4.5 运行态新增字段写入

DynamicCrudService 的新增和更新写入白名单不再只依赖 editSchema：

editSchema 继续作为运行态表单字段白名单。
modelSchema 额外补充设计器保存后已存在真实数据库列的新字段。
仅允许启用、非系统、非主键、非自增、非只读、表单可见且数据库列存在的字段写入。
继续过滤 id、租户、创建人、更新时间等不可变系统字段，避免请求体任意字段透传。

4.6 自动字段清理与默认值策略

表单设计器保存草稿时，buildAutoFieldAssets() 只保留当前表单仍绑定的自动创建字段；未绑定的手工字段资产继续保留，避免高级字段资产被误删。

新版画布 schema 规范化时区分“没有 label”和“用户显式清空 label”：字段组件显式传入空字符串时保留空值，不再回退到“字段”。

DDL 同步时，业务字段的 required 主要作为运行态表单校验。只有当字段配置了非空默认值，才把数据库列同步为 NOT NULL DEFAULT ...；未配置默认值时数据库列保持可空。

5. 影响范围

forge-admin-ui/src/views/app-center/components/designer/BusinessFieldManager.vue
forge-admin-ui/src/views/app-center/components/designer/BusinessFormCreateDesigner.vue
forge-admin-ui/src/views/app-center/components/designer/BusinessFormDesigner.vue
forge-admin-ui/src/views/app-center/components/designer/form-first/fieldReferenceUtils.js
forge-admin-ui/src/views/app-center/components/designer/form-first/forgeBusinessComponents.js
forge-admin-ui/src/views/app-center/components/designer/form-first/forgeToFormCreate.js
forge-admin-ui/src/views/app-center/components/designer/form-first/formCreateToForge.js
forge-admin-ui/src/views/app-center/components/designer/form-first/autoFieldRegistry.js
forge-admin-ui/src/views/app-center/components/designer/form-first/formDesignerSchema.js
forge-admin-ui/src/views/app-center/components/designer/form-first/viewSchema.js
forge-admin-ui/src/views/app-center/object-designer.[objectCode].vue
forge-server/forge-framework/forge-plugin-parent/forge-plugin-generator/src/main/java/com/mdframe/forge/plugin/generator/service/DynamicCrudService.java
forge-server/forge-framework/forge-plugin-parent/forge-plugin-generator/src/main/java/com/mdframe/forge/plugin/generator/service/lowcode/LowcodeDdlService.java

6. 验收标准

在表单设计器拖入输入组件后，可以在属性面板直接输入 customerLevel 作为组件字段 ID。
保存表单设计后，字段资产中出现 customerLevel，字段编码与数据库列名分别为 customerLevel、customer_level。
在字段资产中把字段编码从 customerLevel 改为 customerGrade 后，表单设计器组件绑定同步为 customerGrade，页面/视图引用不遗留旧字段编码。
只进入设计器并切换左侧导航，不弹出“未保存变更”提示。
字段资产页选择字段后直接在页面右侧编辑属性，不出现右侧抽屉弹层。
拖入 form-create 默认输入组件时，rule.field = input、select 等设计器内部默认值不能沉淀为业务字段编码或数据库列名；新字段应生成 fieldInput1 等稳定业务字段编码。
组件绑定已有字段资产后，表单组件标题优先回显字段资产名称，例如选择 customerLevel 时标题同步为“客户等级”。
表单设计器新增字段并同步 DDL 后，运行态新增/编辑记录时该字段值能保存到对应数据库列。
表单里删除自动创建字段后，发布检查不再提示追加该字段对应的数据表列。
新版画布字段“显示名称”可以一次性清空，输入过程中不自动回填。
必填字段未配置默认值时，DDL 不生成 NOT NULL 约束；配置默认值后才生成非空默认值约束。
前端构建、ESLint 或后端目标模块编译等对应变更范围的校验通过；如因既有问题无法全量通过，需在执行日志记录失败点和本次变更无关性。

归档记录（HARD-GATE）

状态：done
归档时间：2026-06-27
归档人：yaomd（批量归档）
归档路径：code-copilot/changes/archive/2026-06-27-lowcode-designer-field-sync-ux/
判定依据：任务清单全部完成，execution-log 验证通过（编译/构建/lint 闭环）。

spec.md 9.3 KB Riwayat Mentahan