# 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 方案在验证中无法满足性能或交互要求。