NVisual 设备双面建模

NVisual 设备双面建模：一套功能，让设备的两面都"看得见"

目录

• 一、一句话说清楚这个功能
• 二、三种使用场景
• 三、功能一：标注端口和槽位属于正面还是背面
• 四、功能二：上传背面背景图，建模视角切换
• 五、功能三：创建实例时自动继承，无需手动操作
• 六、功能四：连线自动归属正确的面
• 七、功能五：双面机柜的正面/背面出线区分
• 八、功能六：面感知的全景视图渲染
• 九、跨面连接的智能校验
• 十、老数据完全兼容，零迁移成本
• 十一、改造涉及范围一览

一、一句话说清楚这个功能

设备建模从"正反面挤在同一张图"升级为"正面/背面两套独立视图"——端口和槽位标记属于哪一面，线缆自动出现在正确的出线面。

升级前后对比

举例：一台 48 口交换机，正面 48 个 GE 口，背面还有电源模块和风扇。升级前这 50+ 个点位全部挤在一张图上，升级后正面视图只展示 48 个 GE 口，切换到背面视图才看到电源和风扇。

二、三种使用场景

三、功能一：标注端口和槽位属于正面还是背面

在设备型号建模页面，为每个端口和槽位新增了一个"面"属性。

操作方式：在端口/槽位的属性面板中，选择正面(face=1)或背面(face=2)。

// 创建端口时传入 face{"name":"GE0/0/1","x":100.0,"y":200.0,"face":1// 1=正面, 2=背面}

效果：

• 同一设备上有正面端口和背面端口时，两边的点位图互不重叠
• 前端根据 face 在对应视图下显示/隐藏端口

四、功能二：正面/背面独立视图 + 各自背景图

升级前，设备建模只有一张图，所有端口全部放在上面——正面 GE 口、背面电源口、管理口……点位多了根本分不清谁在哪。

升级后，右上角新增切换按钮2D 正面 | 2D 背面 | 3D，两点改变：

1. 两张独立背景图：正面视图显示正面面板图，背面视图显示背面面板图
2. 端口按面显隐：切换到背面时正面端口自动隐藏，只显示背面端口

操作方式：在型号管理页面上传背景图时，指定flat=2（背面）：

PUT /wapi/v1/node_types/{nodeTypeId}/set_background_image?flat=2

效果：

• 设备建模详情页支持切换正面/背面视图（右上角新增切换按钮：2D 正面 | 2D 背面 | 3D）
• 切换到背面视图时，显示背面背景图，正面端口自动隐藏，背面端口显示

五、功能三：创建实例时自动继承，无需手动操作

这是本功能最核心的设计：用户在型号上标注好正反面后，创建实例时系统自动处理。

自动发生了什么：

设备型号建模 创建设备实例 ┌──────────────┐ ┌──────────────┐ │ port GE0/0/1 │ face=1 │ port GE0/0/1 │ face 自动=1 │ port GE0/0/48│ face=1 │ port GE0/0/48│ face 自动=1 │ port PSU1 │ face=2 ──→│ port PSU1 │ face 自动=2 │ slot 1 │ face=1 │ slot 1 │ face 自动=1 └──────────────┘ └──────────────┘

用户不用做：

• 不用在实例上再次标注端口面
• 不用手动同步 vis_node 的 face
• 不用关心存储过程或 Java 代码

这一切，创建实例的那一刻就自动完成了。

六、功能四：连线自动归属正确的面

创建设备间连线时，vis_link 自动带上面属性。

行为：

效果：前端根据fromFace和toFace决定线缆从哪个面出线。用户创建连线时不需要手动选择面——系统根据端口自动判定。

七、功能五：双面机柜的正面/背面出线区分

这是正反面建模在机柜视图下的延伸。

场景：双面机柜有两个容器——正面容器（f）和背面容器（b）。设备物理上架到正面容器，但它背面的端口连出的线缆，应该从背面容器出线。

效果：

• 机柜正面容器：展示设备正面 + 正面端口线缆
• 机柜背面容器：展示"虚拟设备"（只展示位置和背面端口） + 背面端口线缆

Diagram 接口新增字段backMountedNodesData，告诉前端设备在背面容器中的对应位置：

{"mountedNodesData":{"containerChildId":866,// 正面容器"rackPosition":42},"backMountedNodesData":{"containerChildId":867,// 背面容器 ← 新增"rackPosition":42}}

前端据此在背面容器渲染一个"影子设备"，位置与正面一致。

八、功能六：全景视图渲染——前端按面过滤

Diagram 详情接口现在返回完整的面信息，前端据此实现按面过滤——升级前所有节点和线缆一并渲染，升级后正面/背面两套视图各显各的。

接口响应新增：

前端渲染策略：

正面视图：显示 face=1 和 face=NULL 的节点/线缆 + 正面背景图 背面视图：显示 face=2 的节点/线缆 + 背面背景图

face=NULL（老数据）只在正面显示，确保历史数据不丢。

九、跨面连接的智能校验

系统自动检测不合理的连接并阻止。

规则：

效果：用户不会无意中在同一设备内部创建跨面回路，减少数据错误。

十、老数据完全兼容，升级零冲击

功能上线后，历史数据的行为与升级前完全一致——所有老数据只有正面视图，没有背面。

用户可以在需要时逐步为设备型号补充背面信息，不用的就维持现状。即：不填补面信息的老设备，表现和升级前完全一样——还是一张视图，正面模式。

十一、改造涉及范围一览

项目：NVisual Lite 网络资源可视化管理系统
技术栈：Spring Boot 2.2.5 + PostgreSQL 13 + PostGIS / Vue 2 + HT for Web
文档版本：v1.0 | 2026-07-31