⚡ SAV 赛唯智能接线图与 SCADA 组态组件集成指南

SAV SCADA 是一套专为电力电网、新能源变电站、工业自动化控制设计的高性能 SVG 矢量一次接线图设计与实时监控运行组件库。系统主要由两大核心组件构成：

1. savConfigToolEdit.vue：智能接线设计与组态编辑器（设计器模式）。
2. savConfigToolView.vue：实时运行监控大屏（运行大屏模式）。

📦 0. 集成前置条件与样式引入

为了保证组态组件能够在您的项目中获得最完美的自适应充满排版及顺畅的运行效果，请在集成前确保满足以下配置：

A. 全局 CSS 基础样式重置

本项目组件内部的所有 UI 排版、发光阴影特效及电力折线流光动画均已采用 Vue 的 作用域 CSS (<style scoped>) 实现自完备。您无需额外引入任何第三方的组件 CSS 样式表。 但为了防止浏览器默认的 body 边距破坏画布平移效果，请确保在您宿主项目的全局 CSS（如 main.js 或入口中）引入如下基础重置样式：

/* 确保父容器及视口撑满全屏，并锁定滚动条 */
html, body, #app {
  margin: 0;
  padding: 0;
  width: 100%;
  height: 100%;
  overflow: hidden;
  background-color: #090d16; /* 推荐采用深色科技底色以配合 SCADA 画布 */
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
}

B. 父级容器大小限制

组态编辑器和大屏大屏均基于 $100%$ 的自适应缩放设计，在集成时，请务必将包裹组件的父级 div 容器的宽高设定为确定的物理宽高（例如 width: 100%; height: 100vh;），以便平移拖动、自适应居中算法（fitToViewport）正确获取尺寸。

C. Pinia 状态库依赖

组件强依赖 Pinia 状态管理以保证撤销、重做历史栈及联动选择的正常运作。如果您的项目尚未集成 Pinia，组件在挂载时内置了动态检测防御机制，会自动为您在全局注册兜底 Pinia 实例，以保障极端情况下组件仍能独立免报错运行。

🛠️ 1. 设计编辑器组件 savConfigToolEdit.vue

用于前端可视化的接线设计排版，支持元器件拖拽、高精磁吸对齐、折线正交寻路、批量对齐、组件锁定以及前置接口拦截。

📦 快速引入与使用

<template>
  <div class="editor-container">
    <savConfigToolEdit 
      ref="editorRef" 
      :config="scadaConfigJson"
      :before-save="handleBeforeSave"
      :before-clear="handleBeforeClear"
      @save="onEditorSave" 
      @clear="onEditorClear" 
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
import savConfigToolEdit from "./components/scada/savConfigToolEdit.vue";

const editorRef = ref(null);
const scadaConfigJson = ref(""); // 传入标准 SCADA 图纸 JSON 字符串以重载图纸

// 1. 【前置异步保存拦截】返回 false 或 Promise<false> 将拦截编辑器的保存提示
const handleBeforeSave = (payload) => {
  return new Promise((resolve) => {
    // 模拟调用后端 API 保存接口
    setTimeout(() => {
      const apiSuccess = true; 
      resolve(apiSuccess);
    }, 800);
  });
};

// 2. 【前置异步清空拦截】返回 false 将拦截并阻止本地画布清空动作，防止脑裂
const handleBeforeClear = (payload) => {
  return new Promise((resolve) => {
    // 模拟调用后端 API 清除画布数据接口
    setTimeout(() => {
      const apiSuccess = true; 
      resolve(apiSuccess);
    }, 800);
  });
};

// 后置保存成功回调
const onEditorSave = (payload) => {
  console.log("保存成功，图纸最新 JSON：", payload.jsonString);
};

// 后置清空成功回调
const onEditorClear = () => {
  console.log("画布已彻底清空");
};
</script>

📋 属性 (Props) 定义

| 属性名 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | config | String / Object | "" | 初始化的 SCADA 图纸配置数据包（格式参照下文数据结构规范） | | beforeSave | Function | null | 保存前置拦截钩子。支持 Promise。若执行返回 false，则不抛出 @save 事件。 | | beforeClear | Function | null | 清空前置拦截钩子。支持 Promise。若执行返回 false，则不清除画布，画面完好无损。 |

🔔 事件 (Events) 定义

| 事件名 | 载荷参数 (Payload) | 说明 | | :--- | :--- | :--- | | @save | { jsonString: String, data: Object, isSilent: Boolean } | 触发保存动作并且前置拦截校验成功后的后置通知事件。 | | @clear | 无 | 触发清空动作并且前置拦截校验成功后的后置通知事件。 |

🖥️ 2. 运行监控大屏组件 savConfigToolView.vue

用于对设计完毕的接线图进行生产环境大屏展示，支持平移拖拽、滚轮缩放、高保真自适应充满屏幕、测点绑定、以及高频实时遥测数据覆盖刷新。

📦 快速引入与使用

<template>
  <div class="viewer-container">
    <savConfigToolView
      ref="viewerRef"
      :config="configData"
      :devices="mockInjectDevices"
      :points="mockInjectPoints"
      :liveData="liveDataMap"
      :debug="true"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
import savConfigToolView from "./components/scada/savConfigToolView.vue";

const configData = ref({}); // 图纸 JSON 结构体
const liveDataMap = ref({}); // 实时高频遥测映射表

// 模拟实时数据源变化：键为测点 Key，值可以为纯数字或 { value, unit } 格式对象
setInterval(() => {
  liveDataMap.value = {
    "pv_inv01_power": parseFloat((Math.random() * 1000).toFixed(1)),
    "pv_trans_status": Math.random() > 0.9 ? 0 : 1, // 开关状态
  };
}, 1500);
</script>

📋 属性 (Props) 定义

| 属性名 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | config | String / Object | 必填 | 传入的组态图纸 Schema 结构体。组件会自动监听变更并重绘。 | | devices | Array | [] | 宿主系统提供的结构化设备拓扑树，用于渲染和检索绑定关系。 | | points | Array | [] | 测点总表。定义了每个测点的 key、单位、上限值和对应设备。 | | liveData | Object | null | 高频实时遥测值映射。如 { "point_key": 220.5 }。传入后，大屏组件上的电流流光速度、断路器变位颜色、遥测文字将立刻自适应渲染。 | | debug | Boolean | false | 若设为 true，大屏右下角会浮现“数据监测抽屉”，便于调试图纸依赖的测点总表。 |

🔌 3. 预设设备树、测点总表与实时遥测数据写入规范

为了实现组态中设备、测点的高精绑定与毫秒级状态联动更新，组件依赖以下三类结构化数据：

A. 预设设备树 (devices Prop)

采用树形节点结构，用于给元器件提供层级设备树检索。

[
  {
    "id": "pv_station_01",
    "label": "新能源光伏电站 1#",
    "children": [
      { "id": "inv_01", "label": "1# 集中式逆变器", "deviceType": "inverter" },
      { "id": "trans_01", "label": "主升压变压器", "deviceType": "transformer" }
    ]
  }
]

B. 预设测点总表 (points Prop)

声明测点的元数据，包含其测点 Key、量纲单位及最高值限额。

[
  {
    "key": "pv_inv01_power",      // 👈 唯一测点标识 Key
    "label": "交流侧有功功率",
    "type": "analog",             // 👈 测点类型：analog (遥测数字/模拟量) 或 switch (遥信开关/状态量)
    "unit": "kW",                 // 👈 物理量单位
    "min": 0,
    "max": 1200,                  // 👈 负荷上限
    "deviceId": "inv_01"          // 👈 关联的设备 ID
  },
  {
    "key": "pv_trans_status",
    "label": "并网控制断路器状态",
    "type": "switch",
    "deviceId": "trans_01"
  }
]

C. 实时数据注入方式 (liveData Prop)

在展示大屏监控页中，从后端数据推送接口（如 WebSocket 或 MQTT）获取高频数据并注入。

• 数据格式：Key-Value 格式映射表，键为测点的 key。为了兼容不同业务系统，值支持以下两种写法：
  1. 纯数值：直接传入 Number，最精炼（如 220.5）。
  2. 结构化对象：支持 { value: Number, unit: String }，大屏会自动解析并优先使用传入的单位进行图绘展示。
• 数据高频写入代码推荐：

  // 1. 父组件中定义响应式数据源
  const liveDataMap = ref({});
    
  // 2. 假设通过 WebSocket 或 Ajax 轮询定时拿到后端大报文
  const onReceiveBackendTelemery = (payload) => {
    // payload 格式如: [ { pointKey: "pv_inv01_power", val: 845.2 }, ... ]
    const newValues = {};
    payload.forEach(item => {
      newValues[item.pointKey] = item.val;
    });
      
    // 3. 修改 liveDataMap 指针，大屏将捕获到变化，并毫秒级同步重绘关联组件与流光状态
    liveDataMap.value = {
      ...liveDataMap.value,
      ...newValues
    };
  };

💾 4. 图纸 JSON 数据结构 Schema 规范

无论是导出、导入还是交给多模态 AI 模型读取以进行智能识图，SAV SCADA 都统一遵守如下规范的 JSON 结构体：

{
  "canvasConfig": {
    "width": 2000,
    "height": 1200,
    "gridSize": 40,
    "gridEnabled": true,
    "gridSnap": true,
    "bgColor": "#090d16"
  },
  "nodes": [
    {
      "id": "node_1",
      "type": "breaker",
      "label": "智能断路器",
      "x": 200,
      "y": 100,
      "width": 120,
      "height": 120,
      "rotate": 0,
      "locked": false,
      "properties": {
        "bindPoint": "breaker_status_01",
        "status": "0"
      }
    }
  ],
  "lines": [
    {
      "id": "line_1",
      "fromNode": "node_1",
      "fromPort": "bottom",
      "toNode": "node_2",
      "toPort": "top",
      "style": "orthogonal",
      "color": "#64748b",
      "width": 2.5,
      "flow": true,
      "properties": {
        "flowColor": "#10b981",
        "bindPoint": "breaker_power"
      }
    }
  ]
}

🏷️ 常用元器件 type 及其基准尺寸建议

为了保证接线图排版的精致和规范，大模型识图或脚本生成时，应尽量使各个组件的 type 与尺寸比例遵循如下标准：

• transformer (双绕组变压器)：$160 \times 240$
• breaker (智能断路器)：$120 \times 120$
• disconnector (隔离刀闸)：$120 \times 120$
• busbar (交流母线)：$480 \times 16$ (支持水平方向横向拉伸)
• switchgear_panel (开关柜体容器)：$240 \times 480$ (支持在其范围内部嵌入其它元器件，建议锁定)
• pipe / pipe_v (独立连接导线)：$480 \times 24$ (横向) / $24 \times 480$ (纵向)
• text (静态纯文本)：$320 \times 80$
• dynamic_text (动态测点显示)：$360 \times 100$
• meter (测量电表)：$240 \times 240$