# 2.1.3 路径点规划功能设计说明

## 2.1.3.1. 模块描述

路径点规划模块是物流路径规划系统的核心功能，针对较为复杂的环境，支持路径点功能。用户可以在三维视图中，在通道上点击指定起点、路径点、终点的位置及方向，并以三维可视化的方式显示路径。该模块支持多条路径的保存、选择和编辑，为物流运输提供精确的路径规划能力。

路径点规划模块与PathPlanningManager、PathClickToolPlugin和PathPointRenderPlugin紧密协作，实现从用户交互到路径生成的完整流程。

## 2.1.3.2. 功能

### 核心功能
1. **路径点创建**：在三维视图中点击创建起点、路径点、终点
2. **方向设置**：为每个路径点设置方向向量
3. **路径生成**：根据路径点自动生成平滑路径
4. **多路径管理**：支持多条路径的创建、保存和切换
5. **三维可视化**：实时显示路径点和路径线

### 子功能
| 功能编号 | 功能名称 | 功能描述 |
|---------|---------|---------|
| 2.1.3.F1 | 起点设置 | 在三维视图中指定路径起点 |
| 2.1.3.F2 | 终点设置 | 在三维视图中指定路径终点 |
| 2.1.3.F3 | 中间点设置 | 添加路径中间点进行路径控制 |
| 2.1.3.F4 | 方向调整 | 调整路径点的方向向量 |
| 2.1.3.F5 | 路径预览 | 实时预览生成的路径 |
| 2.1.3.F6 | 路径编辑 | 编辑已有路径的点位置和方向 |
| 2.1.3.F7 | 多路径切换 | 在多条路径之间切换编辑 |
| 2.1.3.F8 | 路径删除 | 删除不需要的路径 |

## 2.1.3.3. 性能

### 性能指标
| 指标名称 | 目标值 | 说明 |
|---------|-------|------|
| 路径点创建响应 | < 200ms | 点击到点显示的响应时间 |
| 路径生成时间 | < 1秒 | 根据路径点生成完整路径的时间 |
| 支持路径点数量 | > 50个 | 单条路径支持的最大路径点数量 |
| 支持路径数量 | > 100条 | 支持保存的最大路径数量 |
| 渲染帧率 | > 30FPS | 路径可视化渲染帧率 |

### 性能优化策略
1. 使用缓存避免重复的路径计算
2. 路径点批量渲染，减少Draw Call
3. 懒加载策略，非活动路径不渲染

## 2.1.3.4. 输入输出项

### 1. 字段输入输出

#### 输入字段
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| PointType | PathPointType | 是 | 路径点类型（起点/中间点/终点） |
| Position | Point3D | 是 | 路径点三维坐标 |
| Direction | Vector3D | 否 | 路径点方向向量 |
| PathName | string | 否 | 路径名称 |

#### 输出字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| PathRoute | PathRoute | 生成的路径对象 |
| PathLength | double | 路径总长度 |
| EstimatedTime | double | 预估通行时间 |
| PathPoints | List<PathPoint> | 路径点列表 |

### 2. 界面交互输入输出

#### 界面输入
- 鼠标点击选择路径点位置
- 方向调整操作
- 路径参数设置

#### 界面输出
- 三维路径点标记显示
- 路径连线显示
- 路径信息面板显示

## 2.1.3.5. 算法

### 路径点插值算法
```
算法：基于Catmull-Rom样条的路径平滑
输入：路径点列表
输出：平滑路径点列表

1. 对于每对相邻路径点：
   2. 计算控制点（使用前后点作为切线参考）
   3. 使用Catmull-Rom样条插值生成中间点
   4. 将插值点加入结果列表
5. 返回平滑后的路径点列表
```

### 路径生成算法
```
算法：路径点驱动的路径生成
输入：起点、中间点列表、终点
输出：完整路径

1. 创建PathRoute对象
2. 添加起点到路径
3. 对于每个中间点：
   4. 计算与前一点的方向向量
   5. 添加中间点到路径
6. 添加终点到路径
7. 计算路径长度和预估时间
8. 触发路径生成事件
```

## 2.1.3.6. 流程逻辑

```
开始
  │
  ▼
┌─────────────────┐
│  进入路径编辑模式 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  设置起点        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  添加中间点？    │────否────┐
└────────┬────────┘          │
         │是                 │
         ▼                  │
┌─────────────────┐          │
│  点击添加中间点  │          │
└────────┬────────┘          │
         │                   │
         └─────────┬─────────┘
                   │
                   ▼
┌─────────────────┐
│  设置终点        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成路径预览    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│调整点  │  │确认保存│
└───┬────┘  └───┬────┘
    │           │
    └─────┬─────┘
          │
          ▼
         结束
```

## 2.1.3.7. 接口

### 公共接口
```csharp
/// <summary>
/// 路径规划管理器
/// </summary>
public class PathPlanningManager
{
    /// <summary>
    /// 添加路径点
    /// </summary>
    /// <param name="position">点位置</param>
    /// <param name="type">点类型</param>
    /// <returns>创建的路径点</returns>
    public PathPoint AddPathPoint(Point3D position, PathPointType type);
    
    /// <summary>
    /// 生成路径
    /// </summary>
    /// <returns>生成的路径</returns>
    public PathRoute GeneratePath();
    
    /// <summary>
    /// 获取当前路径
    /// </summary>
    /// <returns>当前路径</returns>
    public PathRoute GetCurrentRoute();
    
    /// <summary>
    /// 切换当前路径
    /// </summary>
    /// <param name="routeName">路径名称</param>
    public void SwitchRoute(string routeName);
}
```

### 事件接口
```csharp
/// <summary>
/// 路径点添加事件
/// </summary>
public event EventHandler<PathPointAddedEventArgs> PathPointAdded;

/// <summary>
/// 路径生成完成事件
/// </summary>
public event EventHandler<PathGeneratedEventArgs> PathGenerated;

/// <summary>
/// 当前路径变更事件
/// </summary>
public event EventHandler<RouteChangedEventArgs> CurrentRouteChanged;
```

## 2.1.3.8. 注释设计

### 代码注释规范
```csharp
/// <summary>
/// 路径点类型
/// </summary>
public enum PathPointType
{
    /// <summary>
    /// 起点
    /// </summary>
    Start,
    
    /// <summary>
    /// 中间点（路径点）
    /// </summary>
    WayPoint,
    
    /// <summary>
    /// 终点
    /// </summary>
    End
}

/// <summary>
/// 路径点类
/// 表示路径上的一个关键节点
/// </summary>
public class PathPoint
{
    /// <summary>
    /// 点唯一标识
    /// </summary>
    public string Id { get; set; }
    
    /// <summary>
    /// 点位置（模型单位）
    /// </summary>
    public Point3D Position { get; set; }
    
    /// <summary>
    /// 点方向（用于控制路径走向）
    /// </summary>
    public Vector3D Direction { get; set; }
}
```

## 2.1.3.9. 数据结构

### PathPoint 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Id | string | 点唯一标识符 |
| Position | Point3D | 三维坐标位置 |
| Direction | Vector3D | 方向向量 |
| Type | PathPointType | 点类型 |
| Index | int | 在路径中的索引 |

### PathRoute 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Id | string | 路径唯一标识符 |
| Name | string | 路径名称 |
| Points | List<PathPoint> | 路径点列表 |
| TotalLength | double | 路径总长度（米） |
| EstimatedTime | double | 预估通行时间（秒） |
| CreateTime | DateTime | 创建时间 |

### PathPointAddedEventArgs 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Point | PathPoint | 添加的路径点 |
| PointIndex | int | 点索引 |
| TotalPoints | int | 当前总点数 |