# 多层阶梯式吊装路径开发方案

## 概述

本文档描述多层阶梯式吊装路径（Multi-Level Stepped Hoisting Path）的实现方案。该功能支持在多个水平高度进行正交移动，适用于车间桁车等复杂吊装场景。

### 术语定义

- **单层吊装路径**：传统的"起吊 → 平移 → 下降"三段式路径
- **多层阶梯式吊装路径**：支持在多个高度层进行"提升/下降 → 平移"的阶梯式路径
- **正交路径**：运动严格按 X/Y/Z 轴方向，每次只改变一个维度

## 需求规格

### 功能需求

1. 支持在多个高度层进行水平移动
2. 支持上升和下降过程（可混合）
3. 每个层级可设置不同的水平目标位置
4. 保持与现有单层吊装路径的向后兼容

### 运动轨迹示例

```
单层吊装：
地面起吊 → 提升高度H → 水平移动到终点 → 下降落地
     ↑______________↓

多层吊装（2层提升+1层下降）：
地面起吊 → 提升H1 → 水平移动到P1 → 
           提升H2 → 水平移动到P2 → 
           下降H3 → 水平移动到P3 → 
           下降落地
     ↑______↑______↓______↓
```

## 架构设计

### 数据模型

```
┌─────────────────────────────────────────────────────────────┐
│                      AerialPathParameters                    │
├─────────────────────────────────────────────────────────────┤
│  PathType: PathType.Hoisting                                │
│  StartPoint: Point3D            ← 起吊点（地面）            │
│  EndPoint: Point3D              ← 落点（地面）              │
│  LiftHeightMeters: double       ← 单层模式使用（保留）      │
│  Mode: HoistingMode             ← SingleLevel/MultiLevel    │
│  Levels: List<HoistingLevel>    ← 多层模式层级列表          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       HoistingLevel                          │
├─────────────────────────────────────────────────────────────┤
│  Index: int                     ← 层级序号                  │
│  HeightInMeters: double         ← 相对起吊点的高度          │
│  HorizontalTarget: Point3D      ← 水平目标位置（XY）        │
│  IsRise: bool                   ← true=提升, false=下降     │
│  Description: string            ← 层级描述                  │
└─────────────────────────────────────────────────────────────┘
```

### 兼容性设计

| 组件 | 兼容性策略 |
|------|-----------|
| `PathRoute.Points` | `List<PathPoint>` 天然支持可变数量，无需修改 |
| `PathType.Hoisting` | 继续使用现有枚举值，无需新增 |
| XML序列化 | 按属性序列化，点数不影响格式 |
| 数据库存储 | 路径点表结构不变，仅插入行数变化 |
| `AerialHeightDialog` | 保留现有对话框，单层模式继续使用 |

## 实现计划

### 阶段1：核心数据结构

**目标**：创建数据模型，扩展参数类，实现多层路径生成器

**涉及文件**：
1. `src/Core/PathPlanningModels.cs` - 添加 `HoistingLevel` 类
2. `src/Commands/CreateAerialPathCommand.cs` - 扩展参数和模式枚举
3. `src/PathPlanning/AerialPathGenerator.cs` - 添加多层生成方法

**实现步骤**：
1. 在 `PathPlanningModels.cs` 中添加 `HoistingLevel` 类和 `HoistingMode` 枚举
2. 在 `CreateAerialPathCommand.cs` 中扩展 `AerialPathParameters`
3. 在 `AerialPathGenerator.cs` 中实现 `GenerateMultiLevelHoistingPath` 方法
4. 修改 `CreateAerialPathCommand.ExecuteInternalAsync` 支持两种模式

**向后兼容保证**：
- 现有 `GenerateThreeStepHoistingPath` 方法保持不变
- `AerialPathParameters.LiftHeightMeters` 继续存在
- 新增 `Mode` 属性默认值为 `SingleLevel`

### 阶段2：UI对话框

**目标**：创建多层吊装路径输入对话框

**涉及文件**：
1. `src/UI/WPF/Views/MultiLevelHoistingDialog.xaml` - 新建
2. `src/UI/WPF/Views/MultiLevelHoistingDialog.xaml.cs` - 新建

**功能需求**：
- 显示层级列表（可添加/删除）
- 每个层级设置：高度、方向（提升/下降）、描述
- 水平目标位置通过3D点击获取
- 实时预览路径点数

### 阶段3：ViewModel集成

**目标**：在 PathEditingViewModel 中集成多层模式

**涉及文件**：
1. `src/UI/WPF/ViewModels/PathEditingViewModel.cs`

**功能需求**：
- 添加模式选择命令
- 集成多层对话框
- 支持在创建流程中动态添加层级

## API规范

### HoistingLevel 类

```csharp
public class HoistingLevel
{
    public int Index { get; set; }
    public double HeightInMeters { get; set; }
    public Point3D HorizontalTarget { get; set; }
    public bool IsRise { get; set; }
    public string Description { get; set; }
}
```

### HoistingMode 枚举

```csharp
public enum HoistingMode
{
    SingleLevel,   // 单层（默认，向后兼容）
    MultiLevel     // 多层阶梯式
}
```

### AerialPathParameters 扩展

```csharp
public class AerialPathParameters
{
    // 现有字段保留...
    public HoistingMode Mode { get; set; } = HoistingMode.SingleLevel;
    public List<HoistingLevel> Levels { get; set; }
}
```

### AerialPathGenerator 新方法

```csharp
public List<PathPoint> GenerateMultiLevelHoistingPath(
    Point3D startPoint, 
    Point3D endPoint, 
    List<HoistingLevel> levels)
```

## 测试要点

1. **向后兼容测试**：单层模式路径生成与之前完全一致
2. **多层路径测试**：2层、3层、混合升降路径生成正确
3. **数据序列化测试**：多层路径保存/加载正确
4. **渲染测试**：多层路径在3D视图中正确显示
5. **动画测试**：动画沿多层路径正确插值

## 风险分析

| 风险 | 可能性 | 影响 | 缓解措施 |
|------|-------|------|---------|
| 现有单层功能被破坏 | 低 | 高 | 保留原方法，添加新实现，充分测试 |
| 路径点过多影响性能 | 中 | 中 | 限制最大层级数（如10层） |
| 数据库兼容性问题 | 低 | 高 | 验证现有表结构支持可变点数 |

## 版本记录

| 版本 | 日期 | 描述 |
|------|------|------|
| 1.0 | 2026-02-24 | 初始方案 |