docs: add UML class diagram center design
This commit is contained in:
王鹏
@@ -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 用户 <<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:
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user