# 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.
