194 lines
6.5 KiB
Markdown
194 lines
6.5 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```text
|
||
|
|
用户
|
||
|
|
浏览商品
|
||
|
|
搜索商品
|
||
|
|
查看商品详情
|
||
|
|
筛选商品
|
||
|
|
加入购物车
|
||
|
|
选择规格
|
||
|
|
修改数量
|
||
|
|
直接购买
|
||
|
|
选择规格
|
||
|
|
提交订单
|
||
|
|
选择收货地址
|
||
|
|
选择优惠券
|
||
|
|
支付订单
|
||
|
|
选择支付方式
|
||
|
|
输入支付密码
|
||
|
|
确认收货
|
||
|
|
查看物流
|
||
|
|
评价商品
|
||
|
|
上传图片
|
||
|
|
打分
|
||
|
|
```
|
||
|
|
|
||
|
|
## 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:
|
||
|
|
|
||
|
|
```text
|
||
|
|
角色: 用户
|
||
|
|
用户 -> 浏览商品
|
||
|
|
浏览商品
|
||
|
|
搜索商品
|
||
|
|
查看商品详情
|
||
|
|
评价商品
|
||
|
|
上传图片?
|
||
|
|
```
|
||
|
|
|
||
|
|
## Graph Layout
|
||
|
|
|
||
|
|
Build a deterministic graph object:
|
||
|
|
|
||
|
|
```js
|
||
|
|
{
|
||
|
|
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:
|
||
|
|
|
||
|
|
```js
|
||
|
|
{
|
||
|
|
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.
|