docs: add use case diagram center design
This commit is contained in:
王鹏
@@ -0,0 +1,193 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user