From 36d2415009e4a86776c8a1af7199cdcdf1fac6ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E9=B9=8F?= Date: Tue, 7 Jul 2026 15:21:50 +0800 Subject: [PATCH] docs: add UML class diagram center design --- ...6-07-07-uml-class-diagram-center-design.md | 200 ++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 RuoYi-Vue/docs/superpowers/specs/2026-07-07-uml-class-diagram-center-design.md diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-07-07-uml-class-diagram-center-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-uml-class-diagram-center-design.md new file mode 100644 index 0000000..0aa1014 --- /dev/null +++ b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-uml-class-diagram-center-design.md @@ -0,0 +1,200 @@ +# UML Class Diagram Center Design + +## Goal + +Add a first-class UML class diagram to the EasyCode diagram center. The user-selected design keeps common chart entries visible and moves extended diagram entries into a `更多图表` dropdown. The new `生成 UML 类图` entry should generate an editable UML class diagram from the current project's database tables. + +This is a dedicated project-aware diagram type with `diagramType = 'class_diagram'`, not an AI-only diagram option. + +## Current Context + +`easycode-web/src/views/DiagramCenterView.vue` already supports: + +- Three-line table through `ThreeLineTableView`. +- ER diagram through `ErDiagramView`. +- Function module diagram through `AppModuleDiagramView`. +- Architecture diagram, flowchart, use case diagram, and sequence diagram through DSL editors and SVG previews. +- AI generated diagrams through `generateDiagram`. + +Project diagram drafts already persist through `saveProjectDiagram(projectId, payload)` and restore through `listProjectDiagrams(projectId)`. The class diagram should reuse this draft API and store its DSL plus generated graph inside `diagramJson`. + +## User Experience + +The diagram menu follows option A from the visual review: + +- Keep common entries visible: `三线表`, `ER 图`, `功能模块图`, `系统架构图`, `流程图`, `用例图`, `时序图`, and `AI 生成图`. +- Add a `更多图表` dropdown beside the common entries. +- Add `生成 UML 类图` as the first dropdown item. +- Dropdown items for future UML/state/activity/data-flow diagrams may route to existing AI diagram presets only if they already produce a usable screen; do not add dead entries. + +When the user chooses `生成 UML 类图`, the page switches to the `class_diagram` editor. The editor mirrors the existing DSL-based diagram pattern: + +- A top toolbar with the generated title, class/relation counts, SVG export, and PNG export. +- A left DSL editor panel. +- A right black-and-white UML class diagram preview. +- Inline parse warnings above the preview for recoverable format issues. +- Save and restore through the existing saved diagram list. + +## Default Generation + +Default DSL is generated from the current `database.tables` data: + +- Each table becomes one class. +- Table comment or display name becomes the visible class name when available; table name is retained as metadata. +- Columns become attributes. +- Primary keys are marked with `(PK)`. +- Required columns use a `+` public marker by default only if the project already exposes visibility; otherwise attributes use `-` private markers for a typical UML class view. +- Basic SQL types map to readable types, for example `VARCHAR` to `String`, integer types to `Long` or `Integer`, decimal types to `BigDecimal`, and date/time types to `LocalDateTime`. +- Foreign-key-like columns, manual ER relationships, or obvious `xxx_id` fields become associations when a target table can be inferred. + +If no table data exists, use a small online-store sample so the class diagram page is never blank. + +## DSL Rules + +The first version favors readable text over a full UML language: + +```text +标题: 在线书店 UML 类图 + +class 用户 <> +- id: Long (PK) +- username: String +- password: String ++ login(): Boolean + +class 客户 extends 用户 +- level: Integer +- balance: BigDecimal ++ placeOrder(items: List): Order + +class 订单 +- id: Long (PK) +- totalAmount: BigDecimal ++ pay(): Boolean + +客户 "1" -- "0..*" 订单 : 下单 +``` + +Supported syntax: + +- `标题:` or `title:` sets the diagram title. +- `class 类名` starts a class block. +- Optional stereotypes use `<<...>>`. +- Inheritance can be written as `class 子类 extends 父类` or `子类 --|> 父类`. +- Interface implementation can be written as `class 实现类 implements 接口` or `实现类 ..|> 接口`. +- Attribute lines use `+`, `-`, or `#`, followed by `name: Type`. +- Method lines use `name(args): Type` with an optional visibility prefix. +- Relation lines support association, dependency, inheritance, implementation, aggregation, and composition with labels and cardinalities where present. +- Empty lines and comments beginning with `#` are ignored. + +Recoverable format problems should produce warnings and keep rendering the valid part of the diagram. + +## Graph Layout + +Build a deterministic graph object: + +```js +{ + title, + classes, + relations, + canvas, + stats, + warnings +} +``` + +Rendering rules: + +- Classes render as UML compartments: stereotype/name, attributes, and methods. +- Canvas uses a white background, black/gray strokes, and readable thesis-friendly spacing. +- Class boxes flow in a simple grid with stable dimensions based on content. +- Relation lines route between class boxes and show arrowheads or diamonds for UML relation types. +- Long text is shortened for visible labels while original values remain in graph payload. +- Canvas dimensions grow with class count and row height. + +## Persistence + +Saving uses the existing project diagram API: + +```js +{ + diagramType: 'class_diagram', + title: 'UML 类图', + description: '从数据库表结构生成的 UML 类图草稿', + diagramJson: JSON.stringify({ + dsl, + graph + }) +} +``` + +On load: + +- Prefer a saved `class_diagram` draft and restore its `dsl`. +- If no saved draft exists, generate the default DSL from the project database tables or fallback sample. +- Saved class diagrams appear in the existing saved diagram list and open the dedicated class diagram editor. + +## Components And Utilities + +Add a focused utility module: + +- `easycode-web/src/utils/classDiagram.js` + - `CLASS_DIAGRAM_EXAMPLE_DSL` + - `buildDefaultClassDiagramDsl(project, database)` + - `parseClassDiagramDsl(dsl)` + - `buildClassDiagram(parsed, options)` + - `buildClassDiagramExportSvg(diagram)` + +Integrate it in `DiagramCenterView.vue`: + +- Add `class_diagram` to `normalizeInitialDiagram`. +- Add the `更多图表` dropdown and route `生成 UML 类图` to `class_diagram`. +- Add state for `classDiagramDsl`. +- Add computed values for parsed graph, stats, and relation rendering helpers. +- Add load, save, restore, SVG export, and PNG export handlers. +- Reuse existing workbench styles where possible, with class-specific class names only where needed. + +## Error Handling + +- Empty DSL shows a warning and renders no broken diagram. +- Unknown relation targets remain in warnings and are skipped from the relation layer. +- Malformed attribute, method, or relation lines produce line-numbered warnings. +- Export buttons are disabled when there are no classes. +- Save failures use the existing `ElMessage.error` pattern. + +## Testing + +Use the existing Node test style in `easycode-web/src/utils/*.test.mjs` and `easycode-web/src/views/*.test.mjs`. + +Add `easycode-web/src/utils/classDiagram.test.mjs`: + +- Parses class blocks, attributes, methods, stereotypes, inheritance, implementation, and relation lines. +- Builds default DSL from database tables, including `(PK)` attributes and inferred table associations. +- Exports SVG with class compartments, relation labels, arrowheads, and no `foreignObject`. +- Produces warnings for empty DSL, malformed lines, and missing relation targets. +- Builds a canvas that grows with class count and content height. + +Extend `diagramCenterView.test.mjs`: + +- The diagram center exposes `生成 UML 类图` inside `更多图表`. +- It can open directly through `?diagram=class_diagram`. +- It saves and restores `diagramType: 'class_diagram'`. +- It wires class diagram SVG and PNG export handlers. + +## Non-Goals + +- No drag-and-drop node editing. +- No backend schema changes. +- No new external diagram rendering dependency. +- No complete PlantUML/Mermaid parser. +- No AI prompt changes beyond optional routing from future dropdown entries to existing AI presets. + +## Acceptance Criteria + +- Users can open `图表中心 > 更多图表 > 生成 UML 类图`. +- The first class diagram draft is generated from current project tables when table data exists. +- Users can edit DSL and see an updated UML class diagram preview. +- Users can save and later restore the class diagram draft for a project. +- Users can export SVG and PNG from the current class diagram. +- Focused utility and view tests pass.