Files

王鹏 c1f164a286 docs: add use case diagram center design

2026-07-07 14:45:39 +08:00

6.5 KiB

Raw Blame History

Use Case Diagram Center Design

Goal

Add a first-class use case diagram to the EasyCode diagram center. The new tab should match the SQL2Doc-style reference flow: a text structure editor on the left, a live UML use case diagram preview on the right, and project draft save/export actions integrated with the existing diagram center.

This is not an AI-only diagram option. It is a dedicated diagram type with diagramType = 'use_case'.

Current Context

The frontend diagram center already supports several project-aware diagram types in easycode-web/src/views/DiagramCenterView.vue:

ER diagram through ErDiagramView.
Function module diagram through AppModuleDiagramView.
Architecture diagram through a DSL editor and SVG preview.
Flowchart through a DSL editor and SVG preview.
Three-line table through ThreeLineTableView.
AI generated diagrams through generateDiagram.

Project diagram drafts are already persisted through saveProjectDiagram(projectId, payload) and restored from listProjectDiagrams(projectId). The new use case diagram should reuse that draft API and store its DSL plus generated graph inside diagramJson.

User Experience

Add a 用例图 tab to the diagram type menu. When active, the page shows:

A top toolbar with the generated diagram title, actor/use-case counts, SVG export, and PNG export.
A left editor panel for the use case text structure.
A right preview panel with a black-and-white UML use case diagram.
Inline parse warnings above the preview when the DSL has recoverable format issues.

The default text is generated from the current project when possible. If the project has no usable blueprint, use an e-commerce sample similar to the reference screenshot:

用户
浏览商品
  搜索商品
  查看商品详情
  筛选商品
加入购物车
  选择规格
  修改数量
直接购买
  选择规格
提交订单
  选择收货地址
  选择优惠券
支付订单
  选择支付方式
  输入支付密码
确认收货
  查看物流
评价商品
  上传图片
  打分

DSL Rules

Keep the first version approachable and compatible with the screenshot:

The first non-empty top-level line is the actor, for example 用户.
Later top-level lines are primary use cases.
Lines indented by two or more spaces under a primary use case are included child use cases.
Tabs are normalized to two spaces.
Empty lines are ignored.
Multiple actors can be supported by explicit actor headers later, but the first version optimizes for one main actor.
A line ending with ? marks an optional/exception use case and renders as <<extend>>; otherwise child links render as <<include>>.
Recoverable format issues return warnings instead of breaking the preview.

Future-compatible extended syntax may be accepted where simple:

角色: 用户
用户 -> 浏览商品
浏览商品
  搜索商品
  查看商品详情
评价商品
  上传图片?

Graph Layout

Build a deterministic graph object:

{
  title,
  actors,
  useCases,
  relations,
  canvas,
  stats,
  warnings
}

Rendering rules:

Actor stick figure is placed on the left.
Primary use cases are vertically stacked in the middle as UML ovals.
Included/extended child use cases are placed to the right of their parent.
Actor-to-primary links are solid lines.
Include/extend links are dashed arrows with labels <<include>> or <<extend>>.
Canvas dimensions grow with the number of primary and child use cases.
Long labels are shortened for the visible SVG while the original text remains in the graph payload.

The visual style should stay thesis-friendly: white canvas, black/gray strokes, no decorative colors, and readable spacing.

Persistence

Saving the use case diagram uses the existing saveProjectDiagram path:

{
  diagramType: 'use_case',
  title: '用例图',
  description: 'DSL 驱动的 UML 用例图草稿',
  diagramJson: JSON.stringify({
    dsl,
    graph
  })
}

On load:

Prefer a saved use_case diagram and restore dsl.
If no saved draft exists, generate the default DSL from the project or fallback sample.
Saved use case diagrams should appear in the saved diagram list and open the dedicated 用例图 tab.

Components And Utilities

Add a focused utility module:

easycode-web/src/utils/useCaseDiagram.js
- buildDefaultUseCaseDsl(project)
- parseUseCaseDsl(dsl)
- buildUseCaseDiagram(parsed, options)
- buildUseCaseExportSvg(diagram)

Integrate it in DiagramCenterView.vue:

Add use_case to normalizeInitialDiagram.
Add a 用例图 radio button.
Add state for useCaseDsl.
Add computed values for parsed graph, stats, and labeled relations.
Add load, save, restore, SVG export, and PNG export handlers.

Error Handling

Empty DSL shows a warning and renders no broken diagram.
Missing actor falls back to 用户 with a warning.
Child lines before any primary use case become primary use cases with a warning.
Export buttons are disabled when there are no use cases.
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/useCaseDiagram.test.mjs:

Parses the screenshot-style DSL into one actor, primary use cases, and include relations.
Normalizes tabs to two spaces.
Marks ? child relations as extend relations.
Produces warnings for empty DSL and missing actor.
Builds a canvas that grows with relation count.
Exports SVG with actor, ovals, solid association lines, dashed include/extend lines, and no foreignObject.

Extend diagramCenterView.test.mjs:

The diagram center has a use_case tab.
It can open directly through ?diagram=use_case.
It saves and restores diagramType: 'use_case'.
It wires use case SVG and PNG export handlers.

Non-Goals

No drag-and-drop node editing.
No backend schema changes.
No new external diagram rendering dependency.
No pixel-perfect clone of SQL2Doc branding.
No AI generation changes beyond keeping the existing AI use_case option untouched.

Acceptance Criteria

Users can open 图表中心 > 用例图.
Users can edit a text structure and see a UML use case diagram preview update.
The default sample resembles the provided reference screenshot.
Users can save and later restore the use case diagram draft for a project.
Users can export SVG and PNG from the current use case diagram.
Focused utility and view tests pass.

6.5 KiB Raw Blame History