# 路径分析功能实施计划

> 版本: 1.0  
> 日期: 2026-02-14  
> 总预计工期: 3-4天

---

## 实施阶段概览

| 阶段 | 内容 | 预计工期 | 优先级 |
|-----|------|---------|-------|
| Phase 1 | 核心算法与数据结构 | 1.5天 | P0 - 必须先完成 |
| Phase 2 | UI可视化 | 1天 | P1 - 依赖Phase 1 |
| Phase 3 | HTML报告 | 0.5天 | P2 - 依赖Phase 1 |

---

## Phase 1: 核心算法与数据结构（Day 1-2）

### 任务 1.1: 数据模型（2小时）

**文件**: `src/Core/Models/PathAnalysisModels.cs` (新建)

**内容**:
```csharp
// 主要模型列表：
// 1. PathDetailedAnalysis - 单条路径详细分析结果
// 2. EndpointGroup - 同终点路径组
// 3. CollisionHotspot - 碰撞热点
// 4. PathComparison - 路径对比
// 5. AnalysisStrategies - 策略常量与权重
```

**验收标准**:
- [ ] 所有模型类定义完整
- [ ] 包含所有必要属性
- [ ] XML注释完整

---

### 任务 1.2: 分析引擎（6小时）

**文件**: `src/Core/PathAnalysisEngine.cs` (新建)

**核心方法**:
```csharp
public class PathAnalysisEngine
{
    // 1. 单路径分析
    public PathDetailedAnalysis AnalyzePath(PathRoute route, AnalysisContext context);
    
    // 2. 路径分组（按终点）
    public List<EndpointGroup> GroupPathsByEndpoint(List<PathRoute> routes);
    
    // 3. 热点检测
    public List<CollisionHotspot> DetectHotspots(List<CollisionResult> collisions, double radius);
    
    // 4. 各维度评分
    private double CalculateSafetyScore(int collisionCount, int hotspotCount);
    private double CalculateEfficiencyScore(PathRoute route, double groupMinTime);
    private double CalculateTurnDifficultyScore(List<PathEdge> edges);
    private double CalculateTortuosityScore(PathRoute route);
    private double CalculateRedundancyScore(PathRoute route, List<ChannelInfo> channels);
    
    // 5. 加权评分
    public double CalculateWeightedScore(PathDetailedAnalysis analysis, string strategy);
    
    // 6. 组内最佳路径
    public PathRoute FindBestPathInGroup(EndpointGroup group, string strategy);
}
```

**验收标准**:
- [ ] 能正确计算5维度分数
- [ ] 能正确检测碰撞热点（3米范围，≥2次）
- [ ] 路径分组正确（2米阈值）
- [ ] 加权评分符合权重配置

---

### 任务 1.3: 数据库扩展（3小时）

**文件**: `src/Core/PathDatabase.cs` (修改)

**修改内容**:

1. **CreateTables() 方法** - 扩展 AnalysisResults 表
```sql
-- 新增字段
TurnDifficultyScore REAL
TortuosityScore REAL  
RedundancyScore REAL
HotspotCount INTEGER
AnalysisStrategy TEXT
GroupId TEXT
GroupRanking INTEGER
```

2. **新增方法**:
```csharp
// 保存详细分析结果（扩展）
public void SaveDetailedAnalysisResult(PathDetailedAnalysis analysis);

// 根据RouteId获取最新ClashDetective结果
public ClashDetectiveResultRecord GetLatestClashDetectiveResultByRouteId(string routeId);

// 保存热点数据
public void SaveCollisionHotspots(string routeId, List<CollisionHotspot> hotspots);

// 获取路径的热点数据
public List<CollisionHotspot> GetCollisionHotspots(string routeId);
```

**验收标准**:
- [ ] 新表结构创建成功
- [ ] 数据能正确保存和读取
- [ ] 旧数据兼容性良好

---

### 任务 1.4: 服务层扩展（2小时）

**文件**: `src/Core/PathAnalysisService.cs` (修改)

**修改内容**:

1. **扩展 CompareRoutes 方法**:
```csharp
public PathComparisonResult CompareRoutes(List<PathRoute> routes, string strategy)
{
    // 1. 路径分组
    // 2. 分析每条路径
    // 3. 计算组内排名
    // 4. 找出最佳路径
    // 5. 生成优化建议
}
```

2. **新增方法**:
```csharp
// 分析多条路径并分组
public List<EndpointGroup> AnalyzeAndGroupPaths(List<string> routeIds, string strategy);

// 获取同终点组分析
public EndpointGroupAnalysis GetEndpointGroupAnalysis(string groupId);
```

**验收标准**:
- [ ] 能完成完整分析流程
- [ ] 建议生成合理
- [ ] 与现有代码兼容

---

## Phase 2: UI可视化（Day 2-3）

### 任务 2.1: ViewModel更新（3小时）

**文件**: `src/UI/WPF/ViewModels/PathAnalysisViewModel.cs` (修改)

**新增属性**:
```csharp
// 策略选择（3种）
public List<string> AvailableStrategies { get; }

// 分析结果
public ObservableCollection<PathDetailedAnalysis> AnalysisResults { get; }

// 同终点组
public ObservableCollection<EndpointGroup> EndpointGroups { get; }

// 当前选中组
public EndpointGroup SelectedGroup { get; set; }

// 组内最佳路径
public PathDetailedAnalysis GroupBestPath { get; set; }

// 优化建议（分类）
public ObservableCollection<CategorizedSuggestion> CategorizedSuggestions { get; }
```

**新增命令**:
```csharp
// 切换策略
public ICommand ChangeStrategyCommand { get; }

// 选择组
public ICommand SelectGroupCommand { get; }

// 高亮最佳路径
public ICommand HighlightBestPathCommand { get; }
```

**验收标准**:
- [ ] 数据绑定正确
- [ ] 策略切换触发重新计算
- [ ] 组选择显示详细信息

---

### 任务 2.2: 对话框界面更新（4小时）

**文件**: `src/UI/WPF/Views/PathAnalysisDialog.xaml` (修改)

**布局调整**:

```
左侧面板（300px）:
- 路径选择列表（CheckBox）
- 策略选择（RadioButton，3种）
- [开始分析] 按钮

中间面板（可变）:
- 数据对比表格（5维度分数）
- 雷达图（选中路径）
- 同终点组列表
  - 组标题（终点位置）
  - 组内路径（最佳路径高亮）

右侧面板（300px）:
- 最佳路径卡片
- 优化建议列表（分类）
- [导出报告] 按钮
```

**验收标准**:
- [ ] 布局合理，信息清晰
- [ ] 最佳路径视觉突出
- [ ] 表格数据完整

---

### 任务 2.3: 图表可视化（3小时）

**实现方式**: 使用 WPF 原生图表或简单自定义控件

**图表类型**:
1. **雷达图**: 展示5维度分数
   - 使用 WPF Polygon 实现
   - 或集成简单图表库
   
2. **柱状图**: 组内路径对比
   - 使用 WPF Rectangle 实现
   - 颜色区分不同路径

**文件**: 可在 `PathAnalysisDialog.xaml` 中直接实现，或新建 `PathAnalysisCharts.xaml`

**验收标准**:
- [ ] 雷达图正确显示5维度
- [ ] 柱状图对比清晰
- [ ] 图表随选择更新

---

## Phase 3: HTML报告（Day 3-4）

### 任务 3.1: 报告生成器（4小时）

**文件**: `src/Core/PathAnalysisReportGenerator.cs` (新建)

**核心方法**:
```csharp
public class PathAnalysisReportGenerator
{
    // 生成完整报告
    public string GenerateHtmlReport(PathAnalysisReportData data);
    
    // 生成雷达图数据（纯CSS实现）
    private string GenerateRadarChartCss(PathDetailedAnalysis analysis);
    
    // 生成柱状图数据（纯CSS实现）
    private string GenerateBarChartCss(EndpointGroup group);
    
    // 生成表格HTML
    private string GenerateComparisonTable(List<PathDetailedAnalysis> analyses);
    
    // 保存报告到文件
    public string SaveReportToFile(string htmlContent, string fileName);
}
```

**报告结构**:
```html
1. 头部 - 标题、时间、策略
2. 执行摘要 - 最佳路径推荐（高亮卡片）
3. 雷达图 - CSS实现的5维雷达图
4. 同终点组分析 - 组内对比表格
5. 柱状图 - CSS实现的对比图
6. 优化建议 - 分类建议列表
7. 技术参数 - 物体参数、检测参数
```

**验收标准**:
- [ ] HTML能离线打开
- [ ] 包含所有必要信息
- [ ] 样式专业美观

---

### 任务 3.2: Chart.js本地部署（可选，1小时）

**如需更复杂图表**:

**文件**: 
- 下载 `chart.min.js` 到 `resources/js/`
- HTML中引用 `<script src="./js/chart.min.js"></script>`

**注意**: 如果CSS图表足够，可跳过此步骤

---

## 每日工作计划

### Day 1
| 时间 | 任务 | 输出 |
|-----|------|------|
| 09:00-11:00 | 任务1.1: 数据模型 | PathAnalysisModels.cs |
| 11:00-12:00 | 任务1.3: 数据库扩展（上）| PathDatabase.cs 修改 |
| 14:00-17:00 | 任务1.2: 分析引擎（上）| PathAnalysisEngine.cs 框架 |
| 17:00-18:00 | 任务1.3: 数据库扩展（下）| 完成数据库方法 |

### Day 2
| 时间 | 任务 | 输出 |
|-----|------|------|
| 09:00-12:00 | 任务1.2: 分析引擎（下）| 完成核心算法 |
| 14:00-16:00 | 任务1.4: 服务层扩展 | PathAnalysisService.cs 修改 |
| 16:00-18:00 | Phase 1 测试调试 | 验证算法正确性 |

### Day 3
| 时间 | 任务 | 输出 |
|-----|------|------|
| 09:00-12:00 | 任务2.1: ViewModel更新 | PathAnalysisViewModel.cs |
| 14:00-17:00 | 任务2.2: 对话框界面 | PathAnalysisDialog.xaml |
| 17:00-18:00 | 任务2.3: 图表可视化 | 雷达图/柱状图实现 |

### Day 4
| 时间 | 任务 | 输出 |
|-----|------|------|
| 09:00-12:00 | 任务3.1: 报告生成器 | PathAnalysisReportGenerator.cs |
| 14:00-15:00 | 任务3.2: Chart.js部署（可选）| resources/js/ |
| 15:00-17:00 | 整体测试优化 | 修复问题 |
| 17:00-18:00 | 文档更新 | 更新设计文档 |

---

## 关键检查点

### 检查点1: Phase 1完成（Day 2下午）
- [ ] 能成功分析单条路径
- [ ] 5维度分数计算正确
- [ ] 热点检测正确
- [ ] 数据能保存到数据库

### 检查点2: Phase 2完成（Day 3下午）
- [ ] UI能显示分析结果
- [ ] 雷达图/柱状图正常
- [ ] 同终点组分组正确
- [ ] 最佳路径高亮显示

### 检查点3: 项目完成（Day 4下午）
- [ ] HTML报告生成成功
- [ ] 所有功能集成测试通过
- [ ] 代码审查完成

---

## 风险与应对

| 风险 | 概率 | 影响 | 应对 |
|-----|------|------|------|
| 碰撞位置数据格式不符 | 中 | 高 | 提前检查数据结构，准备备选方案 |
| 通道属性获取复杂 | 中 | 中 | 先使用简化方案，后续优化 |
| WPF图表实现困难 | 低 | 中 | 使用纯CSS图表，或简化显示 |
| 数据库升级失败 | 低 | 高 | 备份数据，使用ALTER TABLE增量升级 |

---

## 交付物清单

### 代码文件
1. `src/Core/Models/PathAnalysisModels.cs` (新建)
2. `src/Core/PathAnalysisEngine.cs` (新建)
3. `src/Core/PathAnalysisReportGenerator.cs` (新建)
4. `src/Core/PathDatabase.cs` (修改)
5. `src/Core/PathAnalysisService.cs` (修改)
6. `src/UI/WPF/ViewModels/PathAnalysisViewModel.cs` (修改)
7. `src/UI/WPF/Views/PathAnalysisDialog.xaml` (修改)
8. `src/UI/WPF/Views/PathAnalysisDialog.xaml.cs` (修改)

### 资源文件
9. `resources/js/chart.min.js` (可选，下载)

### 文档
10. `doc/working/path_analysis_design.md` (已存在)
11. `doc/working/path_analysis_implementation_plan.md` (本文件)

---

## 开始实施

现在开始 **Phase 1 - 任务 1.1: 数据模型**