yunrui_asset/docs/CABLE_WIZARD_GUIDE.md

向导式接线创建功能使用指南

功能概述

新的向导式接线创建功能提供了一种直观、交互式的接线创建流程，帮助用户更高效地管理设备间的物理连接。

核心特性

1. 四步向导流程

步骤 1: 选择源设备

• 搜索并选择接线的起点设备
• 支持设备类型过滤（服务器、交换机、存储设备）
• 点击设备卡片快速选择

步骤 2: 选择目标设备

• 搜索并选择接线的终点设备
• 实时端口冲突检测
• 高亮显示已占用端口

步骤 3: 线缆配置

• 线缆类型选择:

  • 🌐 以太网线（适用于1G/10G短距离连接）
  • 🔦 光纤（适用于长距离或高带宽需求）
  • 🔌 铜缆（适用于电源或特殊设备连接）

• 线缆长度选择:

  • 提供常用长度选项（1m, 2m, 3m, 5m, 7m, 10m, 15m, 20m, 30m, 50m）
  • 自动计算建议长度：根据源/目标设备的机柜位置自动估算所需长度

• 线缆属性设置:

  • 自定义线缆标签（支持自动生成或手动输入）
  • 添加备注说明

步骤 4: 预览确认

• 全面展示接线信息
• 可视化连接预览
• 确认创建接线

2. 端口可视化面板

• 端口状态颜色编码:

  • 🟦 灰色：空闲端口
  • 🟩 绿色：已连接端口
  • 🟥 红色：故障端口

• 端口信息提示:

  • 悬停显示端口详细信息
  • 显示端口类型、速率、VLAN
  • 显示已连接的对端设备信息

• 智能端口选择:

  • 仅显示可用端口
  • 自动过滤已占用端口
  • 冲突端口高亮显示

3. 冲突检测

• 实时检测端口占用情况
• 显示冲突的详细信息
• 提供解决方案建议

使用方法

从设备管理页面创建接线

1. 进入设备管理页面
2. 在交换机设备卡片上找到 "添加接线" 按钮
3. 点击按钮，打开向导式创建界面
4. 按照四步向导完成接线创建

从机柜3D视图创建接线

1. 进入机柜3D可视化页面
2. 在3D场景中选择源设备
3. 点击设备上的端口
4. 选择目标设备的端口
5. 确认接线配置

新增字段说明

Cable 模型新增字段

字段名	类型	说明	示例
cableLabel	VARCHAR(255)	线缆标签/编号	CABLE-001-002-1234
cableColor	VARCHAR(50)	线缆颜色	"红色", "蓝色", "黄色"
installedBy	VARCHAR(100)	安装人	"张三"
installedAt	DATETIME	安装时间	"2024-01-15 10:30:00"
lastTestedAt	DATETIME	上次测试时间	"2024-01-15 11:00:00"

技术实现

前端组件

• CableWizardModal: 向导式接线创建主组件
• PortPanel: 端口可视化面板
• framer-motion: 动画效果

后端 API

• POST /api/cables: 创建接线（支持新字段）
• POST /api/cables/check-conflict: 检查端口冲突
• GET /api/device-ports/device/:deviceId: 获取设备端口列表

数据库迁移

运行以下命令添加新字段：

cd backend
node scripts/migrate-cable-fields.js

最佳实践

1. 线缆标签规范

建议使用以下格式生成线缆标签：

CABLE-{源设备ID后4位}-{目标设备ID后4位}-{时间戳后4位}

示例：

• CABLE-0001-0002-1234
• CABLE-SRV01-SW01-5678

2. 线缆长度估算

系统会根据设备所在机柜的位置自动估算所需长度：

建议长度 = |源机柜ID - 目标机柜ID| × 0.5 + 3

最小长度：3m
最大长度：50m

3. 端口选择建议

• 优先选择相邻的端口（便于管理）
• 同一设备的端口尽量连续分配
• 考虑线缆走线路径，避免交叉

常见问题

Q1: 如何查看已创建的接线？

A: 在接线管理页面可以查看所有接线，支持按状态、类型、设备等条件筛选。

Q2: 如何编辑已创建的接线？

A: 点击接线记录的"编辑"按钮，修改后保存即可。

Q3: 如何删除接线？

A: 点击接线记录的"删除"按钮，确认后删除。

Q4: 端口冲突如何解决？

A: 系统会高亮显示冲突端口，建议选择其他空闲端口或先删除原有连接。

未来扩展

计划功能

1. 批量接线创建

   • 支持 Excel 批量导入
   • 支持模板下载

2. 3D 线缆渲染

   • 在 3D 场景中显示线缆走向
   • 支持线缆路径追踪

3. 接线统计报表

   • 按类型/长度/状态统计
   • 导出 Excel 报表

4. 工单联动

   • 接线操作与工单系统集成
   • 支持变更审批流程

技术支持

如有问题，请联系系统管理员或查看项目文档。