yidaima/RuoYi-Vue/docs/superpowers/specs/2026-07-07-module-diagram-editor-design.md

Module Diagram Editor Design

Goal

Build the function module diagram experience shown in the reference image while preserving the existing EasyCode project-driven diagram flow.

The feature has two entry points:

• Project diagram center: enhance the existing "功能模块图" tab so it can generate the diagram from the saved project blueprint, then let the user adjust layout and export.
• Standalone module diagram editor: provide a SQL2Doc-style editor with a left-side indented structure input and a right-side live module diagram canvas.

Both entry points must share the same parsing, graph layout, SVG rendering, and export logic.

Current Context

The frontend already has:

• easycode-web/src/components/AppModuleDiagramView.vue
• easycode-web/src/utils/appModuleGraph.js
• easycode-web/src/utils/appModuleExport.js
• easycode-web/src/views/DiagramCenterView.vue
• tests for appModuleGraph and appModuleExport

The current graph is already close to the target: it renders a root node, two group nodes, vertical leaf nodes, and black right-angle connectors. The new work should evolve this code rather than replace it with a separate diagram implementation.

User Experience

Diagram Center

In DiagramCenterView.vue, the "功能模块图" view should become a richer workspace:

• Mode switch:
  • 自动蓝图: convert appBlueprint into an editable outline and render it.
  • 缩进结构: let the user edit the outline directly.
• Layout controls:
  • Density: 标准, 宽松, 紧凑
  • Direction: 横向, 竖向
  • Font size: a compact select or segmented control for 小, 标准, 大.
• Export controls:
  • SVG export
  • PNG export
• Save behavior:
  • Save the current outline text, layout options, source mode, and generated graph payload through the existing project diagram save endpoint.

The diagram center remains project-aware. It loads the project name and blueprint, and saving writes back to the project diagram list.

Standalone Editor

Add an editor page that can work with or without a project:

• With projectId: initialize from the project blueprint, allow edits, and save as a project module diagram.
• Without projectId: act as a pure local tool that renders and exports from the typed outline.

The page layout follows the reference:

• Header/tool row for density, direction, font size, and export.
• Left panel for the indented outline text.
• Right panel for the live SVG canvas.
• Helpful empty/error states near the editor rather than modal interruptions.

Custom undo/redo controls are out of scope for this phase. The textarea keeps the browser's native undo/redo behavior.

Input Model

Use a shared outline model as the internal contract:

{
  title: '学生社团管理系统',
  groups: [
    {
      title: '管理员端',
      items: [
        { title: '注册登录' },
        { title: '用户管理' }
      ]
    }
  ]
}

Indented Text Rules

• First non-empty line is the system title.
• Second-level lines are groups/modules.
• Third-level and deeper lines are leaf functions.
• Indentation is counted in spaces. Tabs are normalized to two spaces.
• The editor should accept imperfect input:
  • Blank lines are ignored.
  • A leaf without a group is placed under a fallback group.
  • Deeply nested functions are flattened into leaf titles by default.
• Parsing should return warnings rather than throwing for recoverable issues.

Example:

学生社团管理系统
  管理员端
    注册登录
    用户管理
    社团管理
  普通用户端
    注册登录
    社团浏览
    社团申请

Blueprint Conversion

Convert the existing app blueprint into the same outline model:

• Root title: project name, then blueprint.projectName, then default fallback.
• Admin group: 管理员端, from adminMenus.
• Frontend group: 普通用户端, from frontendMenus.
• Menu title: menu.name, then menu.title, then menu.code.

This keeps automatic project generation and manual editing equivalent.

Graph Layout

Keep a deterministic graph object:

{
  title,
  caption,
  nodes,
  edges,
  groups,
  canvas,
  options
}

Node kinds:

• root
• group
• module

Default horizontal layout:

• Root centered at the top.
• Groups arranged in a row below root.
• Leaf functions arranged below each group.
• Leaf nodes use vertical writing like the reference image.
• Connectors use straight right-angle paths with crisp black strokes.

Density controls tune spacing and sizes, not semantic structure:

• compact: smaller gaps, lower canvas width.
• standard: current default visual balance.
• relaxed: wider gaps for export/readability.

Vertical layout can be introduced as a second layout strategy:

• Root at the left/top.
• Groups stacked or arranged vertically.
• Leaf modules arranged to the right or below each group.

If vertical layout becomes too large, keep horizontal as the production default and make vertical a best-effort option with tests around graph validity.

Components And Utilities

Refactor toward these units:

• appModuleOutline.js
  • parseModuleOutlineText(text)
  • moduleOutlineToText(outline)
  • blueprintToModuleOutline(blueprint, options)
  • normalizeModuleOutline(outline)
• appModuleGraph.js
  • buildAppModuleGraph(source, options)
  • Accept either blueprint or normalized outline.
  • Keep backward compatibility with current callers.
• appModuleExport.js
  • Build standalone SVG from the graph.
  • Exported SVG must match the visible graph style.
• AppModuleDiagramView.vue
  • Pure graph view plus toolbar.
  • Accept blueprint, outline text, and layout options.
  • Emit outline/layout changes when used in editor mode.
• ModuleDiagramEditorView.vue
  • Standalone page with the two-pane editor.
• DiagramCenterView.vue
  • Project-aware host that loads project data, manages save, and embeds the shared component.

Data Flow

Diagram center automatic mode:

project.appBlueprint + project.projectName
  -> blueprintToModuleOutline
  -> moduleOutlineToText
  -> parseModuleOutlineText
  -> buildAppModuleGraph
  -> AppModuleDiagramView
  -> export/save

Standalone editor:

outline textarea
  -> parseModuleOutlineText
  -> buildAppModuleGraph
  -> AppModuleDiagramView
  -> export/save if projectId exists

Error Handling

• Empty input shows an empty state instead of rendering a broken graph.
• Invalid indentation shows non-blocking warnings.
• Export failures use ElMessage.warning.
• Save failures use the existing ElMessage.error pattern in DiagramCenterView.vue.
• Long labels are truncated in horizontal boxes and clipped/ellipsized in vertical leaf boxes.

Testing

Add focused frontend tests before implementation:

• parseModuleOutlineText parses the reference student club outline.
• Tabs normalize to two spaces.
• Missing root or empty input returns an empty outline with warnings.
• blueprintToModuleOutline maps adminMenus to 管理员端 and frontendMenus to 普通用户端.
• buildAppModuleGraph supports a normalized outline source.
• Density options change canvas or spacing predictably.
• Export SVG contains the expected text, rectangles, and paths without foreignObject.

Use existing Node test style in easycode-web/src/utils/*.test.mjs.

Non-Goals

• No drag-and-drop node editing in this phase.
• No AI generation changes in this phase.
• No backend schema change. Store source mode, outline text, layout options, and graph data inside the existing diagramJson payload.
• No pixel-perfect clone of SQL2Doc branding; the goal is the same module diagram workflow and thesis-style output inside EasyCode.

Acceptance Criteria

• Users can open the project diagram center and view a module diagram generated from the project blueprint.
• Users can switch to indented text mode, edit the structure, and see the diagram update.
• Users can open the standalone module diagram editor and build the same style of diagram from text.
• The generated diagram visually matches the reference style: white canvas, black outlined boxes, straight black connectors, vertical leaf labels.
• SVG and PNG exports reflect the current layout settings.
• Saving a project module diagram preserves source mode, outline text, layout options, and graph data.
• Existing module diagram tests continue to pass, and new parser/layout/export tests pass.