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

## 功能概述

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

## 核心特性

### 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`: 获取设备端口列表

### 数据库迁移

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

```bash
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. **工单联动**
   - 接线操作与工单系统集成
   - 支持变更审批流程

## 技术支持

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