AI 低代码 CRUD 可视化搭建体系

status: propose created: 2026-05-19 complexity: 🔴复杂

1. 背景与目标

当前 AI CRUD 模块已经具备自然语言生成配置、配置管理、动态 CRUD 渲染和代码包下载能力，但主要面向技术人员：用户仍需要理解表名、字段名、JSON Schema、接口配置、菜单注册和建表 SQL。新目标是将这些技术细节封装为业务人员可理解的“业务对象、页面组件、字段属性、发布配置”，形成零代码全链路：

可视化数据模型设计 → 拖拽式页面搭建 → 实时效果预览 → 一键在线部署发布

完成后应达到：

业务人员不需要手写代码和 JSON，即可创建一个完整业务管理应用。
平台内置业务组件库可拖拽拼装查询筛选区、数据录入表单、数据展示列表、批量导入、数据导出、批量删除、自定义查询等常见业务能力。
AI 继续作为辅助能力，但生成结果进入可视化模型和页面协议，而不是让用户直接编辑技术配置。
运行时继续复用现有 AiCrudPage、动态 CRUD、字典、脱敏、加解密、菜单注册能力，避免重做已成熟链路。
第一版聚焦单表 CRUD 应用，支持受控在线创建新业务表；树形表按“树形单表”实现；主子表、流程编排和跨表聚合暂不纳入第一版运行时。

2. 代码现状（Research Findings）

2.1 相关入口与链路

forge-admin-ui/src/views/ai/crud-generator.vue：当前 AI CRUD 生成器入口，左侧为对话和历史会话，右侧为配置面板，生成阶段包括元数据、搜索、表格、编辑表单、接口和建表 SQL。
forge-admin-ui/src/views/ai/crud-config.vue：CRUD 配置管理页，当前编辑方式仍以基础信息 + 多个 Schema/JSON 面板为主。
forge-admin-ui/src/views/ai/crud-page.vue：动态渲染页，根据 configKey 调用 /ai/crud-config/render/{configKey}，转换字典、列渲染和模板组件后渲染 AiCrudPage。
forge-admin-ui/src/components/ai-form/AiCrudPage.vue：现有通用 CRUD 渲染核心，已支持搜索区、表格、弹窗/抽屉表单、批量删除、导入按钮、导出按钮、自定义查询、列表/卡片模式。
forge-admin-ui/src/components/form-designer/FormDesigner.vue：已有 Naive UI 风格拖拽表单设计器雏形，左侧组件面板、中间画布、右侧属性面板均已存在，但尚未接入 CRUD 配置保存和整页搭建。
forge-admin-ui/src/catalog/index.js 与 forge-admin-ui/src/components/page-templates/*.vue：当前页面模板注册机制已有 simple-crud 和 tree-crud，可以继续作为低代码页面模板和运行时渲染扩展点。

2.2 现有后端实现

AiCrudConfig 目前持久化 configKey/tableName/tableComment/searchSchema/columnsSchema/editSchema/apiConfig/options/dictConfig/desensitizeConfig/encryptConfig/transConfig/layoutType，缺少业务模型协议、页面布局协议、草稿/发布状态、版本快照。
AiCrudConfigService#createConfig 在创建配置时会立即保存并尝试注册菜单，当前没有“草稿”和“发布”分离。
AiCrudConfigService#getRenderConfig 运行时强制生成动态 CRUD API，使用 :id 占位符，能规避 AI 生成 {id} 的历史问题。
DynamicCrudController 已提供 /ai/crud/{configKey}/page、详情、新增、修改、删除接口，并统一加了 @ApiEncrypt / @ApiDecrypt。
DynamicCrudService 和 DynamicCrudRepository 通过配置驱动动态读写表，已有字段白名单、表名校验、列映射、脱敏、字典翻译和字段加解密处理。
CrudGeneratorStreamService 已支持 SSE 流式阶段输出，并可注入表结构和页面模板约束。
AiCrudConfigGenerateService#buildDescriptionPrompt 原提示词示例使用 {id}，与 AiCrudPage :id 占位符规则不一致；本次已修正为 :id。

2.3 外部方案调研

form-create-designer 是开源 Vue 低代码表单设计器，仓库说明为 MIT License，支持拖拽、JSON 表单规则、扩展组件、表单验证、布局和 AI 助手等能力。
该方案的 Vue3 版本主要面向 Element Plus、Ant Design Vue 和 Vant。本项目主技术栈是 Naive UI，因此直接引入会带来第二套 UI 组件库、样式和打包体积成本。
第一版确认采用 Naive UI 自研搭建器路线，优先复用并增强现有 FormDesigner，抽象 FormDesignerAdapter。后续如确需引入 form-create-designer，通过隔离适配器接入，不让 Element Plus/Antd 依赖污染现有 CRUD 运行时。

2.4 发现与风险

现有能力更像“AI 生成 JSON 配置”，不是“业务应用搭建器”；需要新增业务建模协议和整页布局协议。
在线部署若包含自动建表/改表，属于高风险 DDL 操作，必须加权限、SQL 安全校验、操作日志和发布确认。
当前动态 CRUD 依赖动态表名和动态列名，无法完全按普通业务 SQL 写 Mapper XML；新增查询类管理接口仍必须写 Mapper XML，动态 DDL/CRUD 仅限经过白名单校验的仓储层。
业务数据和系统资源初始化脚本必须使用 tenant_id=1，新增迁移脚本必须做 NOT EXISTS 和 information_schema 防重复保护。
发布会创建或更新菜单资源，属于权限影响范围，必须在 Spec 中标注并经人工确认后进入 /apply。

3. 功能点

新增“低代码应用搭建器”入口，以四步工作台呈现：数据模型、页面搭建、实时预览、发布上线。
数据模型设计器支持新增/编辑字段、字段类型、长度、必填、默认值、字典、枚举、敏感级别、加密策略、是否搜索、是否列表展示、是否表单录入。
数据模型设计器支持两种模式：绑定已有表、创建新业务表。创建新表时生成 DDL 预览，发布时按权限执行。
页面搭建器支持拖拽内置业务组件：查询筛选区、数据表格、编辑表单、详情区、工具栏、批量导入、数据导出、批量删除、自定义查询。
组件属性面板以业务语言配置显示标题、字段来源、控件类型、排序、宽度、校验规则、字典映射、按钮显示、导入导出开关。
实时预览将草稿 modelSchema + pageSchema 转换为 AiCrudPage 所需运行时配置，不要求保存发布即可预览。
一键发布将草稿转换为正式 AiCrudConfig，保存发布版本，必要时执行安全 DDL，注册或更新菜单，启用运行时页面。
支持版本记录和回滚：每次发布保留快照，回滚后恢复配置并更新菜单。
动态 CRUD 支持导入模板、批量导入和数据导出；导入按 editSchema 白名单写入，字典字段支持“标签 -> 值”转换。
支持树形单表：模型协议包含 appType=TREE/treeConfig，页面模板支持左树右表，运行时新增 /ai/crud/{configKey}/tree 树接口。
左树右表支持引用模型作为左侧树数据源，树源表字段与右侧主表过滤字段解耦。
动态导出兼容后台 Excel 列配置表：当存在同 configKey 的列配置时，用其覆盖导出顺序、表头和字典类型；动态查询链路仍保持字段白名单、字典翻译和脱敏。
AI 生成接口兼容返回 modelSchema/pageSchema/options/layoutType，AI 降级时规则引擎同步生成基础低代码协议。
AI SSE 前端交互升级为展示业务模型和页面布局协议，并允许对选中组件或字段做局部优化。
保留现有代码包下载能力，但降级为技术人员入口，业务人员默认只看到可视化搭建和发布。

4. 业务规则

configKey 必须小写字母开头，仅允许小写字母、数字、下划线，长度 2-64。
业务表名必须小写下划线，禁止使用系统表名前缀和 SQL 保留字。
自动创建的新业务表必须包含 id, tenant_id, create_by, create_time, create_dept, update_by, update_time，建议包含 del_flag。
模型字段不能直接暴露基础审计字段给表单录入。
字典字段必须通过字典组件/字典配置驱动，禁止生成硬编码选项。
图片字段存储 fileId，列表预览必须使用 AuthImage 或运行时文件 URL 归一化方案。
页面发布前必须通过模型校验、页面协议校验、API 占位符校验和权限校验。
草稿不会注册菜单，不会对业务用户可见。
发布后菜单路径统一为 /ai/crud-page/{configKey}，组件为 ai/crud-page。
删除已发布应用前，如果菜单已被角色授权，仍沿用现有规则禁止直接删除。
在线 DDL 发布必须具备独立权限，例如 ai:lowcode:deploy-ddl，并记录操作日志。
第一版支持在线创建新表，不支持业务人员在线删除表；在线改表仅允许受控追加字段，不允许删除/改名字段。
第一版支持标准单表和树形单表；运行时写入边界仍是主业务表，左树右表允许引用模型作为只读树源并通过主表外键字段过滤右表。
主子表协议字段已预留，但运行时暂不启用，选择 MASTER_DETAIL 时返回明确业务异常。
发布菜单默认挂载到 AI管理 目录；后续可扩展为管理员选择父菜单。
发布、回滚、删除属于权限影响操作，进入 /apply 前需要人工确认。

5. 数据变更

操作	表名	字段/索引	说明
修改	`ai_crud_config`	`app_name`, `build_mode`, `model_schema`, `page_schema`, `publish_status`, `draft_version`, `published_version`, `publish_time`, `publish_by`	支持低代码草稿、页面协议和发布状态
新增	`ai_crud_config_version`	`config_id`, `config_key`, `version_no`, `version_type`, `model_schema`, `page_schema`, `search_schema`, `columns_schema`, `edit_schema`, `api_config`, `options`, `publish_snapshot`, `remark`	保存发布/回滚版本快照
新增/更新	`sys_resource`	低代码搭建器菜单、低代码应用管理菜单、发布权限按钮	新增脚本必须 `tenant_id=1` 且防重复

5.1 `modelSchema` 协议

{
  "appType": "SINGLE",
  "tableMode": "EXISTING",
  "tableName": "biz_contract",
  "businessName": "合同管理",
  "treeConfig": {
    "sourceModelCode": "",
    "sourceTableName": "",
    "keyField": "id",
    "parentField": "parentId",
    "labelField": "name",
    "filterField": "parentId",
    "targetField": "id",
    "childrenField": "children",
    "treeTitle": "树形导航"
  },
  "fields": [
    {
      "field": "contractName",
      "columnName": "contract_name",
      "label": "合同名称",
      "dataType": "varchar",
      "length": 128,
      "required": true,
      "searchable": true,
      "listVisible": true,
      "formVisible": true,
      "componentType": "input",
      "queryType": "like"
    }
  ]
}

5.2 `pageSchema` 协议

{
  "layoutType": "simple-crud",
  "zones": [
    {
      "zoneKey": "search",
      "componentKey": "search-form",
      "enabled": true,
      "fieldRefs": ["contractName", "status"]
    },
    {
      "zoneKey": "table",
      "componentKey": "data-table",
      "enabled": true,
      "fieldRefs": ["contractName", "amount", "status"],
      "props": {
        "showImport": true,
        "showExport": true,
        "hideBatchDelete": false
      }
    },
    {
      "zoneKey": "edit",
      "componentKey": "edit-form",
      "enabled": true,
      "fieldRefs": ["contractName", "amount", "status"]
    }
  ]
}

6. 接口变更

操作	接口	方法	变更内容
新增	`/ai/lowcode/app/page`	GET	低代码应用分页，参数使用 `pageNum/pageSize`
新增	`/ai/lowcode/app/{id}`	GET	获取应用草稿和发布信息
新增	`/ai/lowcode/app/draft`	POST	新建或保存草稿
新增	`/ai/lowcode/app/{id}/preview`	POST	根据草稿协议返回运行时预览配置
新增	`/ai/lowcode/app/{id}/publish`	POST	发布应用，生成版本、菜单和运行时配置
新增	`/ai/lowcode/app/{id}/versions`	GET	查询发布版本
新增	`/ai/lowcode/app/{id}/rollback/{versionId}`	POST	回滚到指定版本
新增	`/ai/lowcode/model/validate`	POST	校验模型协议
新增	`/ai/lowcode/model/ddl/preview`	POST	生成安全 DDL 预览
新增	`/ai/crud/{configKey}/import`	POST	动态 CRUD 批量导入
新增	`/ai/crud/{configKey}/export`	POST	动态 CRUD 数据导出
新增	`/ai/crud/{configKey}/import-template`	GET	动态 CRUD 导入模板下载
新增	`/ai/crud/{configKey}/tree`	GET	树形单表左侧树数据
修改	`/ai/crud-generator/stream-generate`	POST	支持输出 `modelSchema` 和 `pageSchema` 阶段

7. 影响范围

forge-plugin-generator：配置实体、版本表、低代码服务、发布服务、动态 CRUD 导入导出、AI 生成提示词。
forge-admin-server：菜单注册适配器可能需要支持发布态菜单更新和低代码权限资源。
forge-admin-ui：新增低代码搭建器工作台、模型设计器、页面搭建器、预览和发布入口；现有 crud-generator 和 crud-config 需要调整入口定位。
AiCrudPage：需要补齐由低代码协议驱动的导入导出 URL、图片字段、字典字段和布局配置映射。
数据库迁移：新增 Flyway 版本脚本，初始化菜单和按钮权限。

8. 风险与关注点

⚠️ 涉及权限变更：发布应用会创建或更新菜单资源；删除/回滚会影响菜单可见内容。
⚠️ 涉及状态流转：草稿、已发布、已停用、回滚需要明确状态机，禁止随意 set 状态。
⚠️ 涉及 DDL：在线创建表必须独立权限、SQL 白名单、安全预览、操作日志和失败回滚说明。
不涉及资金变更。
直接引入 form-create-designer 可能带来第二套 UI 组件库，第一版不直接引入运行时依赖。
动态 CRUD 导入导出需要严格限制字段白名单，避免用户上传或导出基础审计字段、加密字段原文。
需要避免 AI 输出 {id} 占位符、硬编码字典选项、tenant_id=0 初始化数据。

8.5 测试策略

测试范围：模型协议校验、运行时配置转换、发布/回滚版本、动态 CRUD 导入导出、前端搭建器交互、预览渲染、菜单注册。
覆盖率目标：新增协议转换、DDL 生成、发布状态机、版本回滚、导入导出字段白名单需要覆盖核心分支。
独立 Test Spec：是，进入 /apply 后补充 code-copilot/changes/visual-lowcode-crud-builder/test-spec.md。
验证命令：
- 后端：mvn -pl forge-admin-server -am compile -DskipTests
- 前端：source ~/.nvm/nvm.sh && nvm use v20.19.0 && pnpm build
- 前端交互：启动 pnpm dev 后用浏览器验证模型设计、拖拽搭建、预览、发布流程。

9. 待澄清

第一版支持受控在线创建新表，发布时需要 ai:lowcode:deploy-ddl 权限和二次确认。
发布菜单第一版默认挂在 AI管理 下，先不开放业务人员任意选择父菜单。
导入导出第一版实现真实 Excel 能力，复用后端 Excel 能力输出基础模板和数据，排在 P1。
第一版聚焦单表 CRUD，不做主子表/明细行。
第一版坚持 Naive UI 自研搭建器，不引入 form-create-designer 及 Element Plus/Antd 相关运行时依赖。

10. 技术决策

第一版采用“增强现有 Naive UI 搭建器 + 适配层”的路线，不直接把 form-create-designer 作为运行时依赖。
低代码协议分为 modelSchema 和 pageSchema，运行时由后端转换为现有 searchSchema/columnsSchema/editSchema/options/apiConfig。
草稿和发布分离：草稿只保存协议，发布才写入正式运行时配置并注册菜单。
版本快照单独建表，避免 ai_crud_config 过度膨胀，也便于回滚审计。
继续复用 /ai/crud/{configKey} 动态 CRUD 运行时，避免为每个低代码应用生成 Java/Vue 文件。
动态页面模板继续使用 catalog + ai_page_template 双注册机制。
在线建表通过专门 DDL 服务生成和执行，只允许单表 CREATE TABLE IF NOT EXISTS 与受控追加字段。
现有 sys_excel_export_config/sys_excel_column_config 面向固定 Service Bean + queryMethod 的导出配置；动态 CRUD 不直接复用固定 Bean 导出引擎，但按 configKey 读取列配置语义，覆盖动态导出列顺序、表头和字典类型。
数据模型的数据源绑定优先写入 modelSchema.sourceTable，不新增模型主表列；运行时和导入同步通过协议中的 datasourceId/datasourceCode/datasourceName/dbType 保留来源。
表单/详情页组件库只维护系统真实可运行的业务组件；左树右表的右表过滤字段在运行时自动补齐树形下拉数据源。

11. 执行日志

Task	状态	实际改动文件	备注
Spec 确认	done	`code-copilot/changes/visual-lowcode-crud-builder/spec.md`, `code-copilot/changes/visual-lowcode-crud-builder/tasks.md`	已确认单表、在线建表、Naive UI 自研
Task 1	done	`forge/db/migration/V1.0.4__add_visual_lowcode_crud_builder.sql`, `AiCrudConfig.java`, `AiCrudConfigVersion.java`, `AiCrudConfigDTO.java`, `AiCrudConfigRenderVO.java`, `AiCrudConfigVersionMapper.java`, `AiCrudConfigVersionMapper.xml`, `AiCrudConfigService.java`	数据库迁移、实体/DTO/VO、版本 Mapper 与基础渲染字段扩展；生成器模块编译通过
Task 2	done	`LowcodeModelSchema.java`, `LowcodeFieldSchema.java`, `LowcodePageSchema.java`, `LowcodePageZone.java`, `LowcodeRuntimeConfig.java`, `LowcodeSchemaValidator.java`, `LowcodeRuntimeConfigBuilder.java`, `AiCrudConfigService.java`	单表协议 DTO、校验器、运行时转换器和渲染链路接入；生成器模块编译通过
Task 3	done	`LowcodeAppDraftDTO.java`, `LowcodePublishDTO.java`, `LowcodeAppDetailVO.java`, `LowcodeVersionVO.java`, `LowcodeAppService.java`, `LowcodePublishService.java`, `MenuRegisterAdapter.java`, `MenuRegisterAdapterImpl.java`, `AiCrudConfigService.java`	草稿/发布分离、菜单注册、版本快照和回滚；正式运行页读取发布态运行时配置
Task 4	done	`LowcodeDdlPreviewDTO.java`, `LowcodeDdlPreviewVO.java`, `LowcodeDdlService.java`, `LowcodeDdlRepository.java`, `DynamicCrudRepository.java`	受控在线建表和追加字段，发布时需 DDL 权限与二次确认，DDL 后刷新动态表缓存
Task 5	done	`LowcodeAppController.java`, `LowcodeModelController.java`, `AiCrudConfigMapper.java`, `AiCrudConfigMapper.xml`	低代码应用分页、详情、草稿、预览、发布、版本、回滚、模型校验和 DDL 预览接口；admin 聚合编译通过
Task 6	done	`DynamicCrudController.java`, `DynamicCrudExcelService.java`, `DynamicCrudService.java`, `DynamicCrudRepository.java`, `DynamicQueryGenerator.java`, `AiCrudPage.vue`, `http/interceptors.js`	动态 CRUD Excel 模板、导入、导出闭环；字典导入按标签反查值，上传下载走统一请求链路
Task 7	done	`src/api/lowcode-crud.js`, `src/views/ai/lowcode-apps.vue`, `src/views/ai/lowcode-builder.vue`, `src/router/index.js`	低代码应用列表、四步工作台入口和动态搭建器路由；前端构建通过
Task 8	done	`LowcodeModelDesigner.vue`, `ModelFieldTable.vue`, `ModelFieldPropertyPanel.vue`, `model-schema.js`, `FieldTypeSelect.vue`, `DictTypeSelect.vue`	Naive UI 自研单表模型设计器，支持字段配置、排序、复制、删除和模型校验
Task 9	done	`LowcodePageBuilder.vue`, `ComponentPalette.vue`, `BuilderCanvas.vue`, `BuilderZone.vue`, `ComponentPropertyPanel.vue`, `page-schema.js`	拖拽式页面区域搭建，生成查询区、列表区、表单区和详情区 pageSchema
Task 10	done	`LowcodePreviewPane.vue`, `PublishPanel.vue`, `VersionTimeline.vue`, `lowcode-builder.vue`, `crud-page.vue`	结构预览、DDL 预览、一键发布和版本回滚面板；运行页接入低代码 options；前端构建通过
Task 12	done	`V1.0.4__add_visual_lowcode_crud_builder.sql`, `crud-config.vue`, `crud-generator.vue`, `ApiConfigEditor.vue`, `provider.vue`, `model.vue`, `AiCrudConfigGenerateService.java`, `SchemaGenerator.java`	低代码菜单和权限初始化，旧入口主路径收敛到低代码工作台，JSON/AI/下载保留为技术入口，API 占位符统一为 `:id`
Task 13	done	`test-spec.md`, `implementation-summary.md`, `forge-docs/guide/lowcode-crud-builder.md`	补充测试规格、实现总结和使用说明；AI 协议深度升级后续单独迭代
Task 14	done	`LowcodeTreeConfig.java`, `LowcodeModelSchema.java`, `LowcodeRuntimeConfigBuilder.java`, `LowcodeSchemaValidator.java`, `DynamicCrudController.java`, `DynamicCrudService.java`, `TreeCrudTemplate.vue`, `LowcodeModelDesigner.vue`, `LowcodePageBuilder.vue`, `ComponentPropertyPanel.vue`, `page-schema.js`, `model-schema.js`	补齐树形单表协议、左树右表运行时、父级字段隐藏查询/写入、搭建器树形配置入口；主子表协议保留但运行时阻断
Task 15	done	`page-schema.js`, `ListPageGridDesigner.vue`, `LowcodePageBuilder.vue`, `CanvasFormDesigner.vue`, `BuilderZone.vue`, `ModelFieldTable.vue`, `model-schema.js`, `LowcodeRuntimeConfigBuilder.java`, `LowcodeSchemaValidator.java`, `DynamicCrudService.java`, `TreeCrudTemplate.vue`	左树右表支持引用模型树源、右表过滤字段与树源字段解耦；表单/详情页改用系统业务组件库；运行态树节点名称归一化兜底
Task 16	done	`lowcode-models.vue`, `LowcodeModelDesigner.vue`, `AiFormItem.vue`, `AiSearch.vue`, `LowcodeRuntimeConfigBuilder.java`, `LowcodeSourceTableRef.java`, `page-schema.js`, `model-schema.js`	模型绑定数据源、ER 图页签、左侧资产导航滚动承载、系统业务选择组件与左树右表表单树形下拉自动配置

12. 审查结论

待实现后审查。

13. 确认记录（HARD-GATE）

确认时间：2026-05-19
确认人：需求方
确认内容：第一版做单表 CRUD，支持受控在线建表，前端采用 Naive UI 自研搭建器。

spec.md 22 KB 히스토리 Raw