DBX ER 图增强架构方案

方案审计与修订说明

DBX 现有操作规范

在描述新方案之前，先明确需要遵循的现有规范。以下内容基于对 SchemaDiagramDialog.vue（v0.5.58）的源码分析。

Dialog 容器结构

<Dialog :open="open" @update:open="(v) => model = v">
  <DialogContent class="w-[94vw] h-[86vh] flex flex-col p-0">
    <DialogHeader class="px-4 py-3 border-b">
      <DialogTitle>Network图标 + "ER 图"标题</DialogTitle>
    </DialogHeader>
    <!-- 工具栏 -->
    <div class="flex items-center gap-2 border-b px-3 py-2 shrink-0 overflow-x-auto">
      ...按钮和选择器...
    </div>
    <!-- 可折叠面板（关系建模 / 匹配管理） -->
    <div v-if="showPanel" class="shrink-0 border-b">...</div>
    <!-- 画布 -->
    <div class="min-h-0 flex-1 bg-muted/20">...</div>
  </DialogContent>
</Dialog>

按钮规范

现有工具栏布局（改造前）

现有存储模式

DBX 的自定义关系存储使用 原生 localStorage，key 格式为 dbx:diagram:relationships:v1:<connectionId>:<database>:<schema>。全项目另有一层安全封装 safeLocalStorageGet/Set/Remove（位于 lib/backend/safeStorage.ts），使用 globalThis.localStorage + try-catch。当前 ER 图模块直接使用原生 localStorage，本方案统一迁移到 safeLocalStorage 封装。

现状分析与核心问题

DBX ER 图当前实现

DBX 的 ER 图功能完全自研，基于原生 HTML/CSS + SVG 渲染，没有引入任何第三方图可视化库。整个功能封装在一个约 1150 行的 SchemaDiagramDialog.vue 组件中。支持两种视图模式（Table View 和 Engineering View），正交折线连线路由（自动绕开中间表卡片），简单网格布局，缩放范围 0.6x - 1.5x，搜索过滤，聚焦模式，自定义关系建模（localStorage 持久化）和 JOIN SQL 自动生成。

与 DataGrip / Navicat 的差距

核心问题

整体架构设计

技术选型

模块拆分

graph TB
    subgraph UI["UI 层 (Vue Components)"]
        A["SchemaDiagramDialog.vue
Dialog 容器 + 工具栏"]
        B["TableNode.vue
表卡片（Vue Flow 自定义节点）"]
        C["RelationshipEdge.vue
关系线（Vue Flow 自定义边）"]
        D["MatchPanel.vue
匹配规则管理面板"]
    end

    subgraph Adapter["适配层"]
        E["VueFlowAdapter
图数据 ↔ VueFlow 格式转换"]
    end

    subgraph Core["核心引擎 (lib/diagram/)"]
        F["GraphStore
Pinia + 撤销/重做历史栈"]
        G["LayoutManager
ELK.js 布局 + 正交边路由"]
        H["MatchEngine
ID 关联智能匹配"]
        I["MatchStorage
匹配规则 localStorage 读写"]
    end

    subgraph Backend["后端 (Rust) — 仅微调"]
        J["schema.rs
+get_all_columns
+ColumnInfo.is_unique"]
    end

    A --> E
    B --> E
    C --> E
    F --> E
    A --> G
    A --> H
    H --> I
    F --> J
      

工具栏改造方案

新工具栏严格沿用 DBX 现有布局：选择器 → 搜索 → 模式切换 → 操作按钮 → Badge → 图标按钮。新增按钮遵循现有 Button 规范，新增图标使用 lucide-vue。Vue Flow 的 Controls 和 MiniMap 作为浮动组件叠加在画布上，不占用工具栏空间。

改造后工具栏布局

新增/变更按钮明细

存储方案

所有匹配相关数据存储在前端 localStorage，使用 DBX 现有的 safeLocalStorageGet/Set/Remove 封装。key 格式与自定义关系保持一致的 dbx:diagram:... 前缀 + "连接 + 数据库 + schema"粒度。

存储 key 设计

存储实现代码

// match-storage.ts
import { safeLocalStorageGet, safeLocalStorageSet, safeLocalStorageRemove }
  from "@/lib/backend/safeStorage";

function matchStorageKey(
  type: "match-confirms" | "match-ignores" | "match-rules",
  connectionId: string,
  database: string,
  schema: string,
): string {
  return ["dbx", "diagram", type, "v1", connectionId, database, schema].join(":");
}

// 加载已确认的匹配关系
export function loadMatchConfirms(
  connectionId: string, database: string, schema: string
): string[] {
  const key = matchStorageKey("match-confirms", connectionId, database, schema);
  try {
    return JSON.parse(safeLocalStorageGet(key) || "[]");
  } catch { return []; }
}

// 保存已确认的匹配关系
export function saveMatchConfirms(
  ids: string[], connectionId: string, database: string, schema: string
): void {
  const key = matchStorageKey("match-confirms", connectionId, database, schema);
  safeLocalStorageSet(key, JSON.stringify(ids));
}

// 加载已忽略的匹配关系
export function loadMatchIgnores(
  connectionId: string, database: string, schema: string
): string[] {
  const key = matchStorageKey("match-ignores", connectionId, database, schema);
  try {
    return JSON.parse(safeLocalStorageGet(key) || "[]");
  } catch { return []; }
}

// 保存已忽略的匹配关系
export function saveMatchIgnores(
  ids: string[], connectionId: string, database: string, schema: string
): void {
  const key = matchStorageKey("match-ignores", connectionId, database, schema);
  safeLocalStorageSet(key, JSON.stringify(ids));
}

// 匹配全局开关（跨连接共享）
export function isAutoMatchEnabled(): boolean {
  return safeLocalStorageGet("dbx:diagram:match-enabled") !== "false";
}

export function setAutoMatchEnabled(enabled: boolean): void {
  safeLocalStorageSet("dbx:diagram:match-enabled", String(enabled));
}

智能 ID 关联匹配引擎

本方案中最有价值的增量能力。DataGrip 通过正则表达式虚拟外键实现了类似功能^[1]，但需要用户手动配置。本方案内置开箱即用的自动匹配策略。

匹配策略分层

匹配算法核心逻辑

function inferRelationships(tables: TableMeta[]): InferredRelationship[] {
  const results: InferredRelationship[] = [];
  const tableNameSet = new Set(tables.map(t => t.name));
  const primaryKeys = buildPrimaryKeyIndex(tables);

  for (const table of tables) {
    for (const column of table.columns) {
      if (column.is_primary_key) continue;

      // P1: 命名约定匹配
      const match = column.name.match(/^(.+?)_(?:id|uuid|pk)$/i);
      if (!match) continue;

      const candidateTable = toSnakeCase(match[1]);
      if (!tableNameSet.has(candidateTable)) continue;

      const targetPK = primaryKeys.get(candidateTable);
      if (!targetPK) continue;

      // P2: 类型签名校验
      if (!isTypeCompatible(column.data_type, targetPK.data_type)) continue;

      results.push({
        sourceTable: table.name,
        sourceColumn: column.name,
        targetTable: candidateTable,
        targetColumn: targetPK.name,
        confidence: 'high',
        strategy: 'naming_convention',
      });
    }
  }
  return deduplicate(results);
}

匹配结果与存储交互

匹配引擎运行时需要与 match-storage.ts 交互，过滤已确认和已忽略的记录：

// match-engine.ts 中的过滤逻辑
function filterByStorage(
  inferred: InferredRelationship[],
  confirms: string[],   // 从 localStorage 加载
  ignores: string[],    // 从 localStorage 加载
): MatchResult {
  const confirmed = inferred.filter(r => confirms.includes(r.id));
  const pending = inferred.filter(r =>
    !confirms.includes(r.id) && !ignores.includes(r.id)
      && r.confidence === 'high'
  );
  const conflicts = pending.filter(r => hasMultipleTargets(r, pending));
  return {
    relationships: [...confirmed, ...pending.filter(r => !conflicts.includes(r))],
    conflicts,
    pending: conflicts,
    stats: { total: inferred.length, high: confirmed.length + pending.length, ... },
  };
}

Vue Flow + ELK.js 交互设计

Vue Flow 提供的开箱即用能力

ELK.js 布局配置

// elk-layout.ts
import ELK from 'elkjs/lib/elk.bundled.js';
const elk = new ELK();

export async function computeLayout(
  graph: DiagramGraph, options: LayoutOptions
): Promise<LayoutResult> {
  const elkGraph = buildElkGraph(graph, options);
  const result = await elk.layout(elkGraph);
  return extractLayoutResult(result);
}

Pinia 原生撤销/重做

不引入第三方撤销库。在 GraphStore（Pinia）中手动维护 historyStack + redoStack，使用 lodash-es 的 cloneDeep 做快照（DBX 已通过 shadcn-vue 间接依赖 lodash-es，无新增依赖）。

// graph-store.ts（核心片段）
export const useGraphStore = defineStore('diagram-graph', () => {
  const nodes = ref<DiagramNode[]>([]);
  const edges = ref<DiagramEdge[]>([]);
  const historyStack = ref<HistorySnapshot[]>([]);
  const redoStack = ref<HistorySnapshot[]>([]);
  const maxHistorySize = 50;

  function pushHistory() {
    historyStack.value.push({
      nodes: cloneDeep(nodes.value),
      edges: cloneDeep(edges.value),
    });
    if (historyStack.value.length > maxHistorySize) historyStack.value.shift();
    redoStack.value = [];
  }

  function undo() {
    if (!historyStack.value.length) return;
    redoStack.value.push({ nodes: cloneDeep(nodes.value), edges: cloneDeep(edges.value) });
    const prev = historyStack.value.pop()!;
    nodes.value = prev.nodes;
    edges.value = prev.edges;
  }

  function redo() { /* 对称实现 */ }

  // 仅布局调整和关系操作记录历史，选择/缩放不记录
  function applyLayout(newNodes: DiagramNode[], newEdges: DiagramEdge[]) {
    pushHistory();
    nodes.value = newNodes;
    edges.value = newEdges;
  }
});

后端改动（最小化）

v4 方案的后端改动仅限于 schema.rs，不新增任何 Tauri Command 或存储模块：

文件结构规划

apps/desktop/src/
├── components/diagram/
│   ├── SchemaDiagramDialog.vue     (重构：拆分为容器 + 工具栏)
│   ├── **TableNode.vue**           (新增：Vue Flow 自定义节点)
│   ├── **RelationshipEdge.vue**    (新增：Vue Flow 自定义边)
│   ├── **MatchPanel.vue**          (新增：匹配管理面板)
│   └── **DiagramToolbar.vue**      (新增：工具栏提取)
│
├── lib/diagram/
│   ├── erDiagram.ts               (保留：核心数据模型)
│   ├── engineeringDiagram.ts      (保留：工程 ER 图)
│   ├── **vue-flow-adapter.ts**   (新增：Vue Flow 适配层)
│   ├── **graph-store.ts**         (新增：Pinia + 撤销/重做历史栈)
│   ├── **layout-manager.ts**      (新增：布局调度)
│   ├── **elk-layout.ts**          (新增：ELK.js 布局配置)
│   ├── **layout-grid.ts**         (新增：网格布局 fallback)
│   ├── **match-engine.ts**        (新增：智能匹配引擎)
│   ├── **match-strategies.ts**    (新增：匹配策略)
│   ├── **match-storage.ts**       (新增：localStorage 读写，复用 safeLocalStorage)
│   └── fieldLineage.ts            (保留)
│
├── types/
│   └── **diagram.ts**             (新增：类型定义)
│
└── tests/
    ├── unit/
    │   ├── **match-engine.test.ts**
    │   ├── **match-storage.test.ts**
    │   ├── **layout-manager.test.ts**
    │   ├── **vue-flow-adapter.test.ts**
    │   └── **graph-store.test.ts**
    └── e2e/
        └── **er-diagram.spec.ts**

src-tauri/src/commands/
└── schema.rs                      (微调：+get_all_columns, +is_unique)

// v3 中的 match_rules.rs 已删除
// v1 中的 edge-router.ts / interaction-manager.ts 已删除（Vue Flow / ELK 替代）

测试方案

单元测试（Vitest）

MatchEngine

MatchStorage

LayoutManager

GraphStore（撤销/重做）

e2e 测试（Playwright）

分阶段实施计划

关键设计决策

为什么工具栏新增按钮而非重新设计

DBX 的工具栏已有固定的布局节奏：选择器 → 搜索 → 模式切换 → 操作按钮 → Badge → 图标按钮。新增的"自动匹配"和"自动布局"按钮插入到操作按钮区域（"建模关系"按钮右侧），遵循 variant="outline" size="sm" class="h-8 px-2 text-xs" + lucide 图标 h-3.5 w-3.5 + mr-1 的规范。缩放和重置按钮移除后由 Vue Flow 的浮动 Controls 组件替代，不占用工具栏空间。这种增量式改动与现有 UI 风格完全一致，PR 审查时不会因为"风格不统一"被要求返工。

为什么用 localStorage 而非新增后端存储

DBX 的自定义关系已使用 localStorage + dbx:diagram:relationships:v1:... key 模式存储。匹配规则的存储需求与自定义关系完全相同（按连接+数据库+schema 隔离、数据量小、JSON 序列化），没有必要引入新的存储机制。使用已有的 safeLocalStorageGet/Set/Remove 封装（而非直接 localStorage），可以统一错误处理，比现有自定义关系代码更健壮。

为什么 ELK.js 直接打包

DBA 常在无网络的内网环境使用数据库管理工具。懒加载在离线场景下会导致布局功能不可用。直接打包后 ELK.js 随安装包分发，增量约 300KB（gzip ~50KB），对 20MB 的 DBX 影响约 1.7%。

为什么不选 Coze 的 FlowGram

FlowGram 基于 Canvas 自研渲染引擎，定位是 AI 工作流编排（内置变量引擎、表单引擎）。Canvas 渲染文本排版远不如 HTML，不适合包含多行列信息的表卡片。对 ER 图来说严重过度设计。

测试用例索引