Domů Procházet Nápověda
Přihlásit se
user5
/
forge_admin
1
0
Rozštěpit 0
Soubory Úkoly 0 Pull Requesty 0 Wiki
Větev: master
Větve Značky
forge_admin
/
code-copilot
/
changes
/
archive
/
2026-06-27-lowcode-form-designer-smooth-dnd
/
spec.md

spec.md 19 KB
Trvalý odkaz Historie Surový

低代码表单设计器顺滑拖拽改造

status: done created: 2026-06-15 complexity: 🔴复杂

1. 背景与目标

当前 /app-center/object/crm_follow_record?suiteCode=IN_OUT 进入“设计对象 → 表单设计”后，中间表单编辑区依赖 FormCreate 通用设计器。它能完成基础拖拽，但体验不符合业务对象设计器的目标：字段资产、布局编排、运行态 CRUD 和发布检查是 Forge 自己的业务链路，FormCreate 画布只理解通用表单组件，导致操作割裂、拖拽反馈弱、布局调整不直观。

本次变更目标是将表单设计器中间画布改造成 Forge 原生设计体验，达到“类似飞书多维表格/表格配置面板”的轻快操作感：

  • 拖拉拽顺滑：拖动过程低延迟、重排无跳动、落点明确。
  • 操作简单：字段、分组、卡片、标签页等常用布局通过少量手势完成。
  • 布局一目了然：字段库、画布、属性面板职责清晰，视觉层级稳定，用户进入页面后能直接理解“从哪里拖、拖到哪里、选中后在哪里改”。
  • 组件细分清楚：画布、节点、拖拽状态、落点提示、属性编辑、字段库和模板入口拆成独立组件/Composable，避免单文件堆叠复杂逻辑。
  • 动效克制但明确：拖动时出现“原位幽灵 + 跟手镜像 + 落点双胞胎阴影”，让用户知道原位置、当前位置和将要放置的位置。
  • 运行态不重做：继续复用现有 AiCrudPage、AiForm、动态 CRUD、发布检查和后端运行配置生成链路。
  • 多端演进可扩展：设计协议继续维护 formDesignerSchema，后续可由 PC Renderer 和 Mobile Renderer 使用同一 Schema 渲染。

可验证结果：

  • crm_follow_record 表单设计不再直接展示 FcDesigner 作为主画布。
  • 用户可从字段库拖入字段、在画布内重排字段、调整字段跨度、放入卡片/分组/标签页。
  • 拖拽时有明确的原位幽灵、跟手镜像、目标位阴影和吸附提示。
  • 所有可拖拽对象 hover 后必须出现明确反馈：拖拽手柄图标、可拖 cursor、边框/背景变化和可操作工具条。
  • 页面布局在 1366x768 下仍可直接看清核心工作区，不出现工具栏挤压、按钮换行错乱或属性面板遮挡画布。
  • 保存、预览、发布、打开运行应用结果继续兼容现有动态 CRUD。
  • 构建通过，关键 schema 编译逻辑有单元或组件级验证。

2. 代码现状（Research Findings）

每个结论必须有代码出处（文件路径 + 类名/方法名）

2.1 相关入口与链路

  • 业务对象详情页入口在 forge-admin-ui/src/views/app-center/object.[objectCode].vue。

    • template 第 18 行和第 95 行通过 openDesigner('form') 打开设计器。
    • 第 163 行嵌入 BusinessObjectDesignerPage，传入 embedded-object-code、embedded-object-id、initial-panel。

  • 业务对象设计器表单面板在 forge-admin-ui/src/views/app-center/object-designer.[objectCode].vue。

    • 第 81 行进入 activePanel === 'form' 面板。
    • 第 84 行挂载 BusinessFormDesigner。
    • 第 86-87 行以 v-model="draft.pageSchema" 和 v-model:form-designer-schema="draft.formDesignerSchema" 同步设计协议。
    • 第 524 行 saveDesignerDraft() 仍走 saveBusinessObjectDesigner() 保存整体设计草稿。

  • 当前中间画布在 forge-admin-ui/src/views/app-center/components/designer/BusinessFormDesigner.vue。

    • 第 51 行挂载 BusinessFormCreateDesigner。
    • 第 221 行引入 saveBusinessObjectDesigner、saveBusinessObjectFormLayout。
    • 第 497 行 syncFormDesignerSchemaToPageSchema() 将 formDesignerSchema 编译进 pageSchema.zones[edit]。

  • FormCreate 嵌入点在 forge-admin-ui/src/views/app-center/components/designer/BusinessFormCreateDesigner.vue。

    • 第 18 行使用 FcDesigner。
    • 第 37 行直接 import @form-create/designer。
    • 第 40 行通过 formCreateBridge 安装 FormCreate + Element Plus 适配。
    • 第 140 行调用 forgeSchemaToFormCreate() 将 Forge Schema 转为 FormCreate rule。
    • 第 166 行 flushDesigner() 再用 formCreateToForgeSchema() 转回 Forge Schema。

2.2 现有实现

  • Forge 自研表单 Schema 已存在于 forge-admin-ui/src/views/app-center/components/designer/form-first/formDesignerSchema.js。

    • 第 14 行 FIELD_COMPONENT_KEYS 定义字段组件。
    • 第 49 行 LAYOUT_COMPONENT_KEYS 同时支持 elCard/card、elTabs/tabs 等双命名。
    • 第 194 行 createDefaultFormDesignerSchema() 能按字段生成默认表单。
    • 第 221 行 normalizeFormDesignerSchema() 负责归一化。
    • 第 340 行 createComponentFromField() 能从字段资产生成组件节点。

  • 表单设计结果已经能编译到运行态：

    • BusinessFormDesigner.vue 第 497 行 syncFormDesignerSchemaToPageSchema() 读取 formDesignerSchema。
    • 第 509 行生成 fieldSettings。
    • 第 510 行生成 formLayout。
    • 第 518 行仍保留 formCreateRule 兼容旧运行逻辑。
    • 第 533 行写入 formLayout。
    • 第 535 行标记 compiledFrom: 'formDesignerSchema'。

  • 运行态已经支持布局节点：

    • forge-admin-ui/src/views/ai/crud-page.vue 第 307 行 transformEditFields() 会读取 options.editFormLayout。
    • 第 325 行 hydrateRuntimeLayoutNode() 将运行布局节点和字段 schema 合并。
    • 第 389 行将水合后的 editSchema 传入 AiCrudPage。
    • forge-admin-ui/src/components/ai-form/AiFormLayoutNodes.vue 第 1 行开始渲染布局节点。
    • AiFormLayoutNodes.vue 第 55 行支持 card。
    • 第 80 行支持 tabs。
    • 第 112 行支持 collapse。
    • 第 143 行支持 divider。

  • 后端运行配置生成已经消费 formLayout：

    • forge-server/forge-framework/forge-plugin-parent/forge-plugin-generator/src/main/java/com/mdframe/forge/plugin/generator/service/lowcode/LowcodeRuntimeConfigBuilder.java 第 55 行 buildRuntimeConfig() 将页面协议转换为 AiCrudPage 运行配置。
    • 第 156 行 buildOptions() 读取编辑区 props。
    • 第 176 行读取 formLayout。
    • 第 178 行写入 options.editFormLayout。

  • 前端已有拖拽依赖和基础用例：

    • forge-admin-ui/package.json 已包含 vuedraggable 与 @vueuse/core。
    • forge-admin-ui/src/components/lowcode-builder/model/ModelFieldTable.vue 使用 vuedraggable 做字段排序。
    • forge-admin-ui/src/components/lowcode-builder/page/BuilderCanvas.vue 使用 vuedraggable 做区块排序。
    • forge-admin-ui/src/components/ai-form/AiTableFilter.vue 已有拖动中/悬停/列表移动样式和 transition-group。

2.3 发现与风险

  • 当前最大体验问题不是运行态 CRUD，而是设计态画布和业务字段资产割裂。
  • FormCreate 设计器需要 Forge Schema ↔ FormCreate Rule 双向转换，任何布局、字段绑定、业务组件都会增加转换损耗。
  • 如果直接拿 AiCrudPage 当设计器画布，会把运行态接口、弹窗、表格和设计态拖拽强绑定，后续维护风险高。
  • 推荐替换 BusinessFormCreateDesigner，保留 BusinessFormDesigner.syncFormDesignerSchemaToPageSchema() 和运行态链路。
  • 拖拽动效必须遵守 prefers-reduced-motion，不能为了“顺滑”引入持续动效或大面积重绘。

3. 功能点

  • [ ] 原生 Forge 表单设计器

    • 输入：formDesignerSchema、字段资产、对象编码、对象名称。
    • 处理：以 Forge Schema 为唯一编辑源，直接增删改排组件树。
    • 输出：更新后的 formDesignerSchema，由现有编译链路生成 pageSchema。

  • [ ] 三栏式设计工作台

    • 左侧：字段资产、布局组件、模板片段。
    • 中间：真实业务画布。
    • 右侧：属性面板。
    • 顶部：表单列数、弹窗/抽屉、预览、补齐字段、撤销重做、清理失效字段。
    • 信息密度按后台工具设计，避免营销式大卡片和过度留白；画布区域优先保证宽度。
    • 所有面板标题、分组、状态数量和空状态必须清楚，用户无需阅读说明即可知道下一步操作。

  • [ ] 飞书多维表格式顺滑拖拽

    • 字段从左侧拖入画布。
    • 画布内字段可重排。
    • 字段可拖入卡片、分组、标签页、折叠面板。
    • 可拖拽对象 hover 后显示拖拽手柄图标，手柄区域使用 cursor: grab，按下后切换 cursor: grabbing。
    • 可拖拽对象 hover 后出现轻量背景、边框或阴影变化，禁用项要明确显示不可拖状态和原因。
    • 拖动时出现：
    • 原位幽灵：原组件保持淡化轮廓，避免用户失去来源位置。
    • 跟手镜像：拖拽卡片跟随指针，使用 transform 和 opacity。
    • 目标位双胞胎阴影：落点位置显示与组件同尺寸的浅色阴影，后方附加一层偏移投影，表达“将复制/移动到这里”的空间感。
    • 吸附线：靠近列边界、容器边界、字段之间时显示落点线。
    • 重排使用 FLIP 思路，非拖拽项以 transform 平滑移动。

  • [ ] 字段操作简化

    • 单击选中字段。
    • 双击字段名可快速改显示标签。
    • 拖动边缘或属性面板调整字段跨度。
    • 快捷操作：复制、删除、隐藏、必填、只读、移到上一行/下一行。
    • 未使用字段可一键补齐。
    • 常用操作必须出现在选中态工具条或右键/更多菜单中，避免用户只依赖右侧属性面板。
    • 危险操作如删除必须有明确按钮样式和二次确认或可撤销策略。

  • [ ] 布局操作简化

    • 支持 title/divider、card、tabs/tabPane、collapse/collapseItem、row/col。
    • 支持“创建分组并移动选中字段进去”。
    • 支持空容器显示可点击落点，避免空容器难以拖入。
    • 支持从常用模板创建布局：基础信息 + 跟进内容 + 时间负责人。

  • [ ] 属性面板

    • 字段属性：标题、占位符、列跨度、必填、只读、默认值、字典、上传限制、关联对象显示字段。
    • 布局属性：标题、描述、列跨度、折叠状态、标签页标题、容器样式。
    • 表单属性：列数、标签位置、标签宽度、行列间距、尺寸、反馈显示。
    • 属性面板按“基础 / 布局 / 校验 / 高级”分组，默认展开常用项，降低认知负担。
    • 所有输入控件必须有清晰 label，不允许只用 placeholder 解释字段含义。

  • [ ] 代码结构与可维护性

    • 新增组件按职责拆分，单个 .vue 文件原则上不承载拖拽、渲染、属性编辑和 schema 操作全部逻辑。
    • 复杂拖拽、落点计算、组件树变更逻辑必须放入独立 composable 或纯函数。
    • 注释只写关键意图和复杂算法说明，例如 FLIP 重排、落点碰撞判断、schema 路径转换；禁止堆砌“赋值/调用”类无效注释。
    • 组件和函数命名要直接表达业务含义，避免 handleData、processItem、tempList 这类泛化命名。

  • [ ] 预览与运行态一致性

    • 设计画布使用与 AiFormLayoutNodes 兼容的节点模型。
    • 保存后继续生成 fieldSettings 和 formLayout。
    • 发布后 AiCrudPage 新增/编辑/详情表单排版与设计器一致。

  • [ ] 兼容旧数据

    • 已保存的 formDesignerSchema 直接读取。
    • 仅存在 FormCreate rule 的旧对象，进入时可转换成 Forge Schema。
    • 保留 BusinessFormCreateDesigner 临时回退入口，便于对比和应急。

4. 业务规则

  • 表单设计器以 Forge formDesignerSchema 为主数据源。
  • 字段组件必须绑定业务字段，布局/虚拟组件不得占用业务字段。
  • 系统字段默认不可拖入主表单，除非后续明确允许只读展示。
  • 已拖入字段在字段库中标记“已使用”，默认不允许重复拖入同一字段。
  • 删除字段组件只从表单布局移除，不删除字段资产。
  • 删除字段资产时必须清理或标记表单中失效引用。
  • 运行态保存和发布仍以 pageSchema、modelSchema、formDesignerSchema 为准。
  • 拖拽动效必须尊重 prefers-reduced-motion：用户开启减少动态效果时，保留落点高亮但禁用跟手弹性和重排动画。
  • 可交互元素必须有明确状态：默认、hover、active、selected、disabled、dragging、drop-target、invalid-drop。
  • 可拖拽元素必须有手柄或图标提示；不能让用户猜测整块区域是否可拖。
  • 面板布局必须服务高频操作：字段库可快速搜索/分组，画布始终是最大视觉区域，属性面板只展示当前选中对象相关内容。
  • 代码结构必须让后续接入移动端 Renderer 时能复用 schema 操作和编译逻辑。

5. 数据变更

操作 表名 字段/索引 说明
无 - - Phase 1 不新增表字段，继续使用现有业务对象设计草稿中的 formDesignerSchema、pageSchema

6. 接口变更

操作 接口 方法 变更内容
无 /ai/business/object/{objectId}/designer GET/PUT 继续读取和保存现有设计器协议
无 /ai/business/object/{objectId}/layout/preview POST 继续使用现有预览生成
无 /ai/business/object/{objectId}/publish POST 继续使用现有发布

7. 影响范围

  • 前端：

    • forge-admin-ui/src/views/app-center/components/designer/BusinessFormDesigner.vue
    • forge-admin-ui/src/views/app-center/components/designer/BusinessFormCreateDesigner.vue
    • 新增 forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/
    • forge-admin-ui/src/views/app-center/components/designer/form-first/formDesignerSchema.js
    • forge-admin-ui/src/components/ai-form/AiFormLayoutNodes.vue

  • 后端：

    • Phase 1 原则上不改后端。
    • 如需增强发布校验，再评估 LowcodeRuntimeConfigBuilder 和业务对象发布检查。

  • 运行态：

    • forge-admin-ui/src/views/ai/crud-page.vue
    • forge-admin-ui/src/components/ai-form/AiCrudPage.vue
    • forge-admin-ui/src/components/ai-form/AiForm.vue

  • 典型验证对象：

    • /app-center/object/crm_follow_record?suiteCode=IN_OUT
    • 跟进记录字段：负责人、主题、关联客户、关联合同/商机、跟进方式、跟进内容、跟进时间。

8. 风险与关注点

  • 拖拽体验风险：如果只用 vuedraggable 默认 ghost class，可能达不到飞书多维表格式顺滑感；需要补自定义 drag overlay、drop indicator 和 FLIP 动效。
  • 布局复杂度风险：三栏工作台如果信息层级不清，会让用户看不懂当前应操作哪里；需要先固定信息架构和面板职责，再做视觉细节。
  • 代码复杂度风险：拖拽、节点渲染、属性编辑如果堆在单个组件里会快速失控；必须拆分组件和 composable，并用纯函数处理 schema。
  • 性能风险：画布字段超过 80 个时，拖动中频繁深拷贝 schema 会卡顿；拖动中应只维护轻量 drag state，落下后一次性提交 schema。
  • Schema 兼容风险：旧 FormCreate rule、旧 formDesignerSchema、当前运行态 formLayout 必须共存过渡。
  • 运行态一致性风险：设计态展示若与 AiFormLayoutNodes 差异过大，会造成“设计看到的不是发布后的样子”。
  • 可访问性风险：拖拽不能成为唯一操作方式，至少要提供按钮上移/下移、移入分组、键盘焦点和可见 focus 状态。
  • 动效风险：过多动画会降低后台工具效率；只在拖拽、选中、插入、撤销重做几个关键点使用 150-240ms 动效。
  • 权限/资金/状态流转：本次不涉及资金、权限放开或业务状态流转。

8.5 测试策略

  • 测试范围：

    • formDesignerSchema 归一化、字段插入、移动、删除、布局容器嵌套。
    • formDesignerSchema -> pageSchema.editZone.props.fieldSettings/formLayout 编译结果。
    • crm_follow_record 保存、预览、发布、打开运行应用。
    • 可拖拽元素 hover、active、disabled、dragging、drop-target 等状态表现。
    • 三栏布局在 1366x768、1440x900、1920x1080 下核心操作区可见。
    • 拖拽交互在 1366x768、1440x900、移动窄屏降级下无重叠。
    • prefers-reduced-motion 下动效降级。

  • 覆盖率目标：

    • Schema 工具函数：覆盖新增移动、插入、删除、路径定位逻辑。
    • 组件交互：覆盖字段拖入、画布内排序、容器内拖入、属性面板修改。
    • 构建验证：pnpm build。

  • 独立 Test Spec：是。进入 /test 前创建或补充 test-spec.md，并按 code-copilot/rules/automated-testing-standard.md 追加 execution-log.md。

9. 待澄清

  • 第一阶段是否允许完全隐藏 FormCreate 画布，只保留高级回退开关？
  • 是否需要首期支持移动端预览模式，还是只预留 schema 字段后续做 H5 Renderer？
  • “双胞胎阴影”的视觉强度是否以轻量后台风格为准：浅蓝边框 + 白色主体 + 第二层偏移阴影？
  • 是否要把 crm_follow_record 内置一个推荐布局模板：基础信息、跟进对象、跟进内容、时间负责人？
  • 拖拽手柄图标优先使用现有 Iconify/UnoCSS 图标，还是统一使用 @vicons/ionicons5 图标？

10. 技术决策

  • 决策 1：设计态不直接复用 AiCrudPage 页面壳。

    • 原因：AiCrudPage 是运行态组件，包含接口、弹窗、表格、导入导出、流程详情等职责；设计态应只复用字段渲染资产和布局协议。

  • 决策 2：Forge formDesignerSchema 作为设计态唯一事实来源。

    • 原因：现有 schema 已支持字段组件、布局组件、归一化、默认生成和运行态编译，替换画布不需要重写后端和动态 CRUD。

  • 决策 3：Phase 1 不引入新拖拽依赖，优先使用已有 vuedraggable + 自定义 Pointer/Overlay/FLIP。

    • 原因：项目已有 vuedraggable，可覆盖列表和嵌套排序；复杂镜像和吸附提示由自研 composable 控制，减少依赖风险。

  • 决策 4：动效只用 transform、opacity、box-shadow，禁止拖拽中修改布局尺寸做动画。

    • 原因：降低重排和卡顿风险，保证后台工具效率。

  • 决策 5：保留 FormCreate 兼容转换，但从主链路下线。

    • 原因：旧数据迁移和应急回退需要一段过渡期。

11. 执行日志

Task 状态 实际改动文件 备注
Proposal done spec.md, tasks.md 已创建改造提案
Native designer skeleton done BusinessFormDesigner.vue, formDesignerSchema.js, forge-form-designer/* 新版三栏画布骨架接入，旧 FormCreate 画布保留回退
Validation done test-spec.md, execution-log.md eslint、pnpm build、git diff --check 通过

12. 审查结论

待 /review lowcode-form-designer-smooth-dnd 执行。

13. 确认记录（HARD-GATE）

  • 确认时间：待确认
  • 确认人：待确认

归档记录（HARD-GATE）

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