227 lines
8.0 KiB
Markdown
227 lines
8.0 KiB
Markdown
# EasyCode ER 图中心设计方案
|
||
|
||
## 背景
|
||
|
||
当前项目已经在 `easycode-web` 前台项目工作台中提供图表中心页面，并具备基础 ER 图能力：
|
||
|
||
- `easycode-web/src/views/DiagramCenterView.vue` 负责图表中心入口、图表切换、草稿保存和导出。
|
||
- `easycode-web/src/components/ErDiagramView.vue` 已能基于数据库设计渲染表结构卡片、拖动节点、手工添加关系、导出 PNG。
|
||
- `front_project_diagram` 已能保存 `diagram_type = er` 的图表草稿。
|
||
- `easycode-web/src/api/project.js` 已有项目、数据库、图表草稿相关接口封装。
|
||
|
||
本次目标是把现有 ER 图升级为截图所示的 ER 图工作台：SQL 输入、实体筛选、Chen 风格实体属性图、默认布局、一键美化、样式控制、导出和草稿恢复。
|
||
|
||
## 范围
|
||
|
||
本功能入口只放在 `easycode-web` 前台项目工作台，不在 `ruoyi-ui` 后台管理端新增菜单或页面。
|
||
|
||
允许补充必要后端能力，主要是 SQL DDL 解析接口和图表草稿持久化复用。后端能力只服务 `easycode-web` 前台项目工作台，不作为后台工具菜单交付。
|
||
|
||
## 用户体验
|
||
|
||
页面采用截图中的三栏结构：
|
||
|
||
- 左侧为 SQL 输入区，支持清空、加载示例、换一换、上传 `.sql` 文件、重新生成。
|
||
- 中间为实体列表，显示已选实体数和关系数，支持全选、单表勾选、实体搜索。
|
||
- 右侧为 ER 画布，顶部提供基础 ER 图和系统 ER 图标签。首期实现基础 ER 图，系统 ER 图预留入口。
|
||
|
||
画布工具栏包含：
|
||
|
||
- 重新生成：基于当前 SQL 或当前数据库设计重新构建 ER 图。
|
||
- 默认布局：恢复稳定网格布局。
|
||
- 一键美化：按关系密度和实体数量重新布局。
|
||
- 主键下划线：开关主键属性文字下划线。
|
||
- 线条粗细：控制关系线和属性线粗细。
|
||
- 字体：提供默认、紧凑、论文三种字体方案。
|
||
- 导出：支持 PNG、SVG、JSON。
|
||
|
||
画布交互包含：
|
||
|
||
- 鼠标滚轮缩放。
|
||
- 拖动画布平移。
|
||
- 拖动实体节点，属性节点跟随实体移动。
|
||
- 双击实体或属性改显示名。
|
||
- 选中实体列表后实时隐藏未选实体。
|
||
|
||
## ER 图模型
|
||
|
||
前端统一使用标准化后的 ER 图模型：
|
||
|
||
```json
|
||
{
|
||
"version": 2,
|
||
"sql": "CREATE TABLE ...",
|
||
"selectedTableNames": ["user", "order"],
|
||
"tables": [
|
||
{
|
||
"tableName": "user",
|
||
"tableComment": "用户表",
|
||
"columns": [
|
||
{
|
||
"columnName": "id",
|
||
"columnComment": "用户ID",
|
||
"columnType": "bigint",
|
||
"isPk": "1",
|
||
"isIncrement": "1",
|
||
"isRequired": "1"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"relations": [
|
||
{
|
||
"id": "order.user_id->user.id",
|
||
"source": "order",
|
||
"sourceField": "user_id",
|
||
"target": "user",
|
||
"targetField": "id",
|
||
"inferred": true
|
||
}
|
||
],
|
||
"layout": {
|
||
"entities": {
|
||
"user": { "x": 120, "y": 180 }
|
||
}
|
||
},
|
||
"style": {
|
||
"primaryKeyUnderline": true,
|
||
"lineWidth": 1,
|
||
"fontPreset": "default"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 图形呈现
|
||
|
||
基础 ER 图采用 Chen 风格：
|
||
|
||
- 实体使用矩形节点，显示中文表名优先，英文表名作为辅助信息。
|
||
- 属性使用椭圆节点，围绕实体排布，显示中文字段注释优先，字段名作为辅助信息。
|
||
- 主键属性文字带下划线。
|
||
- 属性与实体之间使用细线连接。
|
||
- 实体关系线根据外键或 `xxx_id` 字段推断生成。
|
||
|
||
布局策略：
|
||
|
||
- 每个实体内部采用椭圆环绕布局，字段数量较少时均匀环绕，字段数量较多时分左右两列。
|
||
- 多实体默认按网格布局排列，保证截图中类似的疏朗效果。
|
||
- 一键美化时优先把存在关系的实体放近，孤立实体放到外侧。
|
||
- 保存草稿后优先恢复用户拖动后的实体坐标。
|
||
|
||
## SQL 解析
|
||
|
||
SQL 解析放在后端实现，复用项目中已有的 Druid SQL 解析能力，避免前端用正则拆 SQL。
|
||
|
||
新增接口：
|
||
|
||
```text
|
||
POST /front/project/{projectId}/er/parse-sql
|
||
```
|
||
|
||
入参：
|
||
|
||
```json
|
||
{
|
||
"sql": "CREATE TABLE `user` (...)"
|
||
}
|
||
```
|
||
|
||
出参：
|
||
|
||
```json
|
||
{
|
||
"tables": [],
|
||
"relations": [],
|
||
"warnings": []
|
||
}
|
||
```
|
||
|
||
解析范围：
|
||
|
||
- MySQL `CREATE TABLE`。
|
||
- 表名、表注释。
|
||
- 字段名、字段类型、字段注释。
|
||
- 主键、自增、非空。
|
||
- 唯一键和索引可作为后续展示信息保留。
|
||
- 显式外键优先生成关系。
|
||
- 没有显式外键时，根据 `xxx_id` 字段推断关系。
|
||
|
||
异常处理：
|
||
|
||
- 非 `CREATE TABLE` 语句忽略并返回 warning。
|
||
- 无法解析的片段返回 warning，不影响其他表生成。
|
||
- SQL 为空时前端提示用户输入 SQL 或先生成数据库设计。
|
||
|
||
## 持久化
|
||
|
||
继续复用 `front_project_diagram`：
|
||
|
||
- `diagram_type = er`
|
||
- `title = ER 图`
|
||
- `diagram_json` 保存完整 ER 草稿 JSON
|
||
|
||
数据库设计本身仍通过现有数据库保存接口维护。ER 图草稿只保存图形视图状态、SQL 输入、筛选状态、关系草稿和布局样式，不替代项目数据库设计。
|
||
|
||
## 前端改造
|
||
|
||
建议拆分如下文件：
|
||
|
||
- `easycode-web/src/views/DiagramCenterView.vue`：保留图表中心容器，负责数据加载、保存、导出和图表切换。
|
||
- `easycode-web/src/components/er/ErSqlPanel.vue`：SQL 输入、示例、上传和重新生成。
|
||
- `easycode-web/src/components/er/ErEntityList.vue`：实体筛选、全选、数量统计。
|
||
- `easycode-web/src/components/er/ErToolbar.vue`：默认布局、一键美化、样式控制、导出按钮。
|
||
- `easycode-web/src/components/er/ErChenCanvas.vue`：SVG 画布、缩放、平移、节点拖拽、双击改名。
|
||
- `easycode-web/src/utils/erChenGraph.js`：把数据库表模型转换为实体、属性、关系图模型。
|
||
- `easycode-web/src/utils/erLayout.js`：默认布局和一键美化布局。
|
||
- `easycode-web/src/utils/erDraft.js`：草稿合并、版本升级、默认值补齐。
|
||
- `easycode-web/src/utils/erExport.js`：扩展现有导出，支持 Chen 图 SVG/PNG。
|
||
|
||
## 后端改造
|
||
|
||
建议新增：
|
||
|
||
- `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/ParseErSqlRequest.java`
|
||
- `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/ParseErSqlResponse.java`
|
||
- `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/SqlDdlParseService.java`
|
||
|
||
建议修改：
|
||
|
||
- `ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java`：新增 SQL 解析接口。
|
||
- `easycode-web/src/api/project.js`：新增 `parseErSql(projectId, data)`。
|
||
|
||
## 分阶段交付
|
||
|
||
### 阶段一：ER 图工作台 UI 和 Chen 图
|
||
|
||
用当前项目数据库设计生成 Chen 风格 ER 图，补齐实体筛选、默认布局、一键美化、样式控制、导出和草稿保存。此阶段不依赖 SQL 解析，能先替换现有卡片式 ER 图体验。
|
||
|
||
### 阶段二：SQL 输入和解析
|
||
|
||
新增后端 SQL 解析接口，前端左侧 SQL 输入接入解析结果。支持粘贴 SQL、上传 SQL 文件、加载示例和重新生成。
|
||
|
||
### 阶段三：关系增强和编辑
|
||
|
||
完善显式外键、推断关系、手工关系编辑、关系删除、关系数量统计。允许用户调整关系后保存到草稿。
|
||
|
||
### 阶段四：验证和体验收口
|
||
|
||
补前端工具函数单测、后端 SQL 解析单测，验证中文注释、多表、大字段量、导出清晰度、移动端布局和草稿兼容。
|
||
|
||
## 验收标准
|
||
|
||
- ER 图中心入口只在 `easycode-web` 前台项目工作台出现。
|
||
- 当前项目数据库设计可以直接生成截图风格 ER 图。
|
||
- 粘贴 MySQL `CREATE TABLE` SQL 后可以生成实体、属性和关系。
|
||
- 实体列表勾选能实时控制画布显示。
|
||
- 主键属性默认下划线展示。
|
||
- 支持默认布局、一键美化、拖动实体、缩放和平移。
|
||
- 草稿保存后刷新页面能恢复 SQL、筛选、布局和样式。
|
||
- 支持 PNG、SVG、JSON 导出。
|
||
|
||
## 非目标
|
||
|
||
- 不在 `ruoyi-ui` 后台管理端新增 ER 图中心。
|
||
- 不在第一版实现多人协同编辑。
|
||
- 不在第一版实现完整数据库建模器替代功能。
|
||
- 不在第一版引入大型图形编辑库，除非原生 SVG 方案在验证中无法满足性能或交互要求。
|