97 lines
4.3 KiB
Markdown
97 lines
4.3 KiB
Markdown
# 系统架构图 DSL 编辑器设计
|
||
|
||
## 目标
|
||
|
||
将现有 `图表中心 > 系统架构图` 从简单横向节点图升级为截图风格的架构图编辑器。用户进入页面时，系统根据当前项目数据自动生成一份架构图 DSL 初稿；用户可编辑 DSL、生成预览、保存草稿，并导出 SVG/PNG。
|
||
|
||
## 当前基础
|
||
|
||
- 前端已有 `easycode-web/src/views/DiagramCenterView.vue`，提供 ER 图、功能模块图、架构图、项目总览图和 AI 图表入口。
|
||
- 架构图当前由 `buildArchitectureGraph()` 生成通用节点图，缺少 DSL 编辑、分层架构布局和横切关注点侧栏。
|
||
- 图表保存已经通过 `saveProjectDiagram(projectId, payload)` 写入 `front_project_diagram`，`diagramType='architecture'` 可复用。
|
||
- 导出能力已有 SVG/PNG 浏览器端实现，可继续复用。
|
||
|
||
## DSL 语法
|
||
|
||
采用缩进文本 DSL，贴近截图中的编辑体验：
|
||
|
||
```text
|
||
用户层
|
||
学生
|
||
选课 / 查成绩
|
||
教师
|
||
课程管理 / 成绩录入
|
||
表现层 - Vue 3 前端
|
||
Vue 3
|
||
Composition API
|
||
Vue Router 路由
|
||
横切关注点
|
||
JWT 认证
|
||
登录签发 Token
|
||
```
|
||
|
||
规则：
|
||
|
||
- 顶格行为层名，可用 ` - ` 或 `—` 附加副标题。
|
||
- 缩进 2 个空格为组件标题。
|
||
- 缩进 4 个空格为组件说明，可多行。
|
||
- 层名为 `横切关注点` 时，不进入主纵向架构流，而是渲染到右侧关注点栏。
|
||
- 空行忽略；无法归类的行尽量按最近层/组件吸收，避免用户轻微格式错误导致整图不可用。
|
||
|
||
## 默认 DSL 生成
|
||
|
||
进入系统架构图时优先加载已保存的 `architecture` 草稿；若没有保存草稿，则根据当前项目数据生成默认 DSL：
|
||
|
||
- 用户层：从 `appBlueprint.roles` 或项目菜单推断角色，缺省为“普通用户/管理员”。
|
||
- 表现层：使用 Vue 3、Element Plus、Axios，补充前台/后台菜单数量。
|
||
- 接口层：Spring MVC Controller、统一接口规范、统一响应封装。
|
||
- 业务逻辑层：从业务模块、菜单或数据库表提取服务组件，缺省提供用户服务、业务服务、文件服务。
|
||
- 持久层：MyBatis、Mapper、分页和连接池。
|
||
- 数据层：MySQL、本地文件系统，展示表数量。
|
||
- 运行环境：Windows/Mac、JDK 8+、Node.js 16+、Spring Boot、MySQL。
|
||
- 横切关注点：JWT 认证、全局异常、接口规范、跨域配置。
|
||
|
||
## 交互设计
|
||
|
||
`activeDiagram === 'architecture'` 时显示专用编辑器：
|
||
|
||
- 顶部工具栏显示“系统架构图”、层数/组件数统计、黑白模式、保存、导出 SVG、导出 PNG。
|
||
- 左侧为 DSL 编辑区，提供“清空”“加载示例”“换一换”“生成预览”。
|
||
- 右侧为可滚动 SVG 预览，主架构层纵向排列，层之间用箭头连接；横切关注点在右侧独立粉色侧栏显示。
|
||
- 预览失败时保留编辑区，右侧显示可诊断的空态或错误提示。
|
||
- 保存时写入 `diagramJson`，结构包含 `dsl`、`graph`、`blackWhite`，后续重新进入页面可恢复。
|
||
|
||
## 渲染设计
|
||
|
||
新增前端工具模块负责纯函数处理：
|
||
|
||
- `buildDefaultArchitectureDsl(project, database, blueprint)`：生成默认 DSL。
|
||
- `parseArchitectureDsl(dsl)`：解析为 `{ layers, concerns, stats, errors }`。
|
||
- `buildArchitectureDiagram(parsed, options)`：计算 SVG 坐标、画布尺寸、层/组件/箭头数据。
|
||
- `buildArchitectureExportSvg(diagram, options)`：输出可下载 SVG 字符串。
|
||
|
||
布局采用固定宽度、响应式外层滚动：
|
||
|
||
- 主层宽约 620px，组件按每行 3 个排列。
|
||
- 横切关注点侧栏宽约 190px，高度跟随主图。
|
||
- 根据组件数量自动增加每层高度。
|
||
- 黑白模式仅改变色彩，不改变 DSL、坐标或保存结构。
|
||
|
||
## 测试
|
||
|
||
新增 `easycode-web/src/utils/architectureDiagram.test.mjs`：
|
||
|
||
- 默认 DSL 生成包含项目名、前端/后端/数据库核心层。
|
||
- DSL 解析能识别层、副标题、组件、说明和横切关注点。
|
||
- 布局统计能正确返回层数、组件数，画布尺寸随内容增加。
|
||
- 导出 SVG 包含层标题、组件标题和关注点内容。
|
||
- 保存恢复结构保持 DSL 和图数据字段稳定。
|
||
|
||
## 非目标
|
||
|
||
- 不接 AI 生成 DSL。
|
||
- 不做拖拽移动组件。
|
||
- 不做历史撤销/重做。
|
||
- 不新增后端接口或数据库字段。
|
||
- 不替换 ER 图、功能模块图、项目总览图的现有实现。
|