NavisworksTransport/doc/introduction/2.3.3_路径时间标签功能设计说明.md

# 2.3.3 路径时间标签功能设计说明

## 2.3.3.1. 模块描述

路径时间标签模块是层级创建功能的重要组成部分，负责支持路径时间标签设置，以预估运输时间。该模块通过分析路径的长度、元素类型（如门、电梯、楼梯的速度限制）等因素，计算物流运输的预估时间，为路径规划提供时间维度的参考。

该模块与TimeTagService、TimeTagCalculator和PathRoute紧密集成，实现基于路径特征的时间估算功能。

## 2.3.3.2. 功能

### 核心功能
1. **时间估算**：基于路径特征估算运输时间
2. **分段计时**：对路径的不同段进行分段计时
3. **时间标签显示**：在路径上显示时间标签
4. **速度限制应用**：应用通道元素的速度限制
5. **时间导出**：导出时间估算结果

### 子功能
| 功能编号 | 功能名称 | 功能描述 |
|---------|---------|---------|
| 2.3.3.F1 | 路径分析 | 分析路径的长度、坡度等特征 |
| 2.3.3.F2 | 速度计算 | 根据元素类型计算各段速度 |
| 2.3.3.F3 | 时间计算 | 计算总运输时间和分段时间 |
| 2.3.3.F4 | 时间标签 | 在路径点显示时间标签 |
| 2.3.3.F5 | 分段显示 | 显示各段的预计时间 |
| 2.3.3.F6 | 时间导出 | 导出时间数据到文件 |
| 2.3.3.F7 | TimeLiner集成 | 与TimeLiner任务时间同步 |

## 2.3.3.3. 性能

### 性能指标
| 指标名称 | 目标值 | 说明 |
|---------|-------|------|
| 时间计算响应 | < 200ms | 计算路径时间的响应时间 |
| 批量计算时间 | < 1秒 | 批量计算多条路径的时间 |
| 标签渲染时间 | < 100ms | 渲染时间标签的时间 |
| 内存占用 | < 50MB | 时间计算的额外内存占用 |

### 性能优化策略
1. 缓存路径特征计算结果
2. 批量时间计算优化
3. 时间标签按需渲染

## 2.3.3.4. 输入输出项

### 1. 字段输入输出

#### 输入字段
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| Route | PathRoute | 是 | 要计算时间的路径 |
| ObjectSpeed | double | 否 | 物体移动速度（米/秒），默认0.8 |
| ApplySpeedLimits | bool | 否 | 是否应用速度限制，默认true |

#### 输出字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| TotalTime | double | 总运输时间（秒） |
| SegmentTimes | List<SegmentTime> | 分段时间列表 |
| TimeTags | List<TimeTag> | 时间标签列表 |
| AverageSpeed | double | 平均速度（米/秒） |

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

#### 界面输入
- 路径选择
- 速度参数设置
- 时间标签显示选项

#### 界面输出
- 总时间显示
- 分段时间表
- 时间标签可视化
- 导出结果提示

## 2.3.3.5. 算法

### 时间估算算法
```
算法：基于路径特征的时间估算
输入：路径，物体速度
输出：时间估算结果

1. 初始化总时间为0
2. 对于路径的每个段：
   3. 获取段长度
   4. 获取段的元素类型和速度限制
   5. 计算段速度：
      - 取物体速度和速度限制的较小值
   6. 计算段时间：长度 / 速度
   7. 累加到总时间
8. 返回总时间和分段详情
```

### 分段计时算法
```
算法：路径分段计时
输入：路径点列表
输出：分段时间列表

1. 对于每对相邻路径点：
   2. 计算两点间距离
   3. 识别经过的物流元素
   4. 获取元素的速度限制
   5. 计算通过时间
   6. 记录分段信息
7. 返回分段时间列表
```

## 2.3.3.6. 流程逻辑

```
开始
  │
  ▼
┌─────────────────┐
│  选择路径        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  分析路径特征    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  获取速度限制    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  计算分段时间    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  计算总时间      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成时间标签    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│显示标签│  │导出时间│
└───┬────┘  └───┬────┘
    │           │
    └─────┬─────┘
          │
          ▼
         结束
```

## 2.3.3.7. 接口

### 公共接口
```csharp
/// <summary>
/// 时间标签服务
/// </summary>
public class TimeTagService
{
    /// <summary>
    /// 计算路径时间
    /// </summary>
    /// <param name="route">路径对象</param>
    /// <param name="objectSpeed">物体速度</param>
    /// <returns>时间计算结果</returns>
    public TimeCalculationResult CalculatePathTime(PathRoute route, double objectSpeed = 0.8);
    
    /// <summary>
    /// 生成时间标签
    /// </summary>
    /// <param name="result">时间计算结果</param>
    /// <returns>时间标签列表</returns>
    public List<TimeTag> GenerateTimeTags(TimeCalculationResult result);
    
    /// <summary>
    /// 在视图中显示时间标签
    /// </summary>
    /// <param name="timeTags">时间标签</param>
    public void DisplayTimeTags(List<TimeTag> timeTags);
    
    /// <summary>
    /// 导出时间数据
    /// </summary>
    /// <param name="result">时间计算结果</param>
    /// <param name="filePath">导出路径</param>
    public void ExportTimeData(TimeCalculationResult result, string filePath);
}
```

### 辅助接口
```csharp
/// <summary>
/// 时间计算器
/// </summary>
public class TimeTagCalculator
{
    /// <summary>
    /// 计算段的通过时间
    /// </summary>
    public double CalculateSegmentTime(PathSegment segment, double speed);
    
    /// <summary>
    /// 获取元素的速度限制
    /// </summary>
    public double GetSpeedLimit(ModelItem element);
}
```

## 2.3.3.8. 注释设计

### 代码注释规范
```csharp
/// <summary>
/// 时间计算结果
/// </summary>
public class TimeCalculationResult
{
    /// <summary>
    /// 总运输时间（秒）
    /// </summary>
    public double TotalTimeSeconds { get; set; }
    
    /// <summary>
    /// 总运输时间（格式化为 mm:ss）
    /// </summary>
    public string TotalTimeFormatted => FormatTime(TotalTimeSeconds);
    
    /// <summary>
    /// 分段时间详情
    /// </summary>
    public List<SegmentTimeInfo> SegmentTimes { get; set; }
    
    /// <summary>
    /// 平均速度（米/秒）
    /// </summary>
    public double AverageSpeed { get; set; }
}

/// <summary>
/// 分段时间信息
/// </summary>
public class SegmentTimeInfo
{
    /// <summary>
    /// 段索引
    /// </summary>
    public int SegmentIndex { get; set; }
    
    /// <summary>
    /// 段长度（米）
    /// </summary>
    public double Length { get; set; }
    
    /// <summary>
    /// 通过时间（秒）
    /// </summary>
    public double TimeSeconds { get; set; }
    
    /// <summary>
    /// 段速度（米/秒）
    /// </summary>
    public double Speed { get; set; }
}
```

## 2.3.3.9. 数据结构

### TimeCalculationResult 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| TotalTimeSeconds | double | 总运输时间（秒） |
| SegmentTimes | List<SegmentTimeInfo> | 分段时间列表 |
| AverageSpeed | double | 平均速度（米/秒） |
| RouteName | string | 路径名称 |
| CalculationTime | DateTime | 计算时间 |

### SegmentTimeInfo 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| SegmentIndex | int | 段索引 |
| StartPoint | PathPoint | 起点 |
| EndPoint | PathPoint | 终点 |
| Length | double | 段长度（米） |
| TimeSeconds | double | 通过时间（秒） |
| Speed | double | 段速度（米/秒） |
| ElementType | LogisticsElementType | 主要元素类型 |

### TimeTag 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Position | Point3D | 标签位置 |
| TimeValue | double | 时间值（秒） |
| TimeText | string | 时间显示文本 |
| LabelType | TimeTagType | 标签类型 |

### TimeTagType 枚举
| 值 | 说明 |
|---|------|
| Start | 起点时间 |
| Segment | 分段点 |
| Cumulative | 累计时间 |
| End | 终点时间 |