From c1f164a2867d9ec375d7dc6ca52256764e344a21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E9=B9=8F?= Date: Tue, 7 Jul 2026 14:45:39 +0800 Subject: [PATCH] docs: add use case diagram center design --- ...26-07-07-use-case-diagram-center-design.md | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 RuoYi-Vue/docs/superpowers/specs/2026-07-07-use-case-diagram-center-design.md diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-07-07-use-case-diagram-center-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-use-case-diagram-center-design.md new file mode 100644 index 0000000..54cdc94 --- /dev/null +++ b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-use-case-diagram-center-design.md @@ -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 `<>`; otherwise child links render as `<>`. +- 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 `<>` or `<>`. +- 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.