yidaima/RuoYi-Vue/docs/superpowers/specs/2026-07-07-uml-class-diagram-center-design.md

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:

标题: 在线书店 UML 类图

class 用户 <<abstract>>
- 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:

{
  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:

{
  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.