diff --git a/doc/design/2026/free-path-design.md b/doc/design/2026/free-path-design.md new file mode 100644 index 0000000..a40226b --- /dev/null +++ b/doc/design/2026/free-path-design.md @@ -0,0 +1,131 @@ +# 自由路径(Free Path)设计方案 + +> 分支:`feature/free-path` +> 创建日期:2026-06-30 +> 状态:设计中(详见下方"实施进度跟踪") + +--- + +## 一、背景与问题 + +### 1.1 现状 + +当前路径类型 `PathType`: + +| 值 | 类型 | 说明 | +|----|------|------| +| 0 | Ground | 地面路径 | +| 1 | Rail | 空轨路径 | +| 2 | Hoisting | 吊装路径 | + +**2点路径**:是 Hoisting 上的 `IsTwoPointVertical` 特殊标志,非独立类型。语义混乱: + +| | 起点 | 终点 | +|----|------|------| +| 动画帧循环 | 底面中心对齐(`ResolveGroundTrackedCenter`) | 几何中心(`p2` 原始点) | +| 终点诊断 | — | 底面中心对齐(又一种) | + +**问题**:起点用底面中心对齐、终点用几何中心对齐,**对齐语义不一致**; +且 2 点路径被绑死在吊装逻辑中,无法作为通用路径使用。 + +### 1.2 需求 + +1. 2 点路径改为**自由路径(Free)**,从吊装路径中剥离 +2. 与地面、空轨、吊装等路径**并列**为一级路径类型 +3. **统一包围盒中心对齐**:每个路径点 = 物体几何中心 +4. 支持**任意多个自由路径点** + +--- + +## 二、目标 + +1. 新增一级 `PathType.Free` +2. 统一包围盒中心对齐(轨迹即物体中心) +3. 支持任意多点自由路径 +4. 从吊装剥离,废弃 `IsTwoPointVertical` 特殊逻辑 +5. 温和迁移旧 2 点吊装路径数据 + +--- + +## 三、核心设计 + +### 3.1 PathType 枚举 + +```csharp +public enum PathType +{ + Ground = 0, + Rail = 1, + Hoisting = 2, + Free = 3 // 新增 +} +``` + +- `GetDisplayName()` 增加 `case PathType.Free: return "自由";` +- DB 存储为整数,**追加枚举值向后安全**,无需 schema 迁移 + +### 3.2 动画语义(关键) + +自由路径的每个路径点**就是物体包围盒中心**: + +```csharp +framePosition = 路径点直接插值; // 不加任何半高偏移 +``` + +- 起点/终点/中间点**统一**用几何中心对齐(无起点/终点不对称) +- 天然满足"矢量任意方向"——不依赖哪个面是底 + +### 3.3 旋转姿态策略(决策点1 → 方案1) + +**方案1(已确认)**:forward = 路径切线方向,up = 世界 up 投影正交化。 + +- 复用 `RailPathPoseHelper` 的三维姿态计算 +- 物体保持"上"朝世界,像车沿坡道走 +- 通用且符合物流车语义 + +### 3.4 创建流程(UI) + +- 新增"自由路径"创建模式,与地面/空轨/吊装并列 +- 用户连续点击任意 3D 点(即物体中心轨迹) +- 无地面约束、无提升/下降段逻辑 +- 支持任意点数,最后设终点完成 + +### 3.5 渲染 + +- 自由路径按普通多点线渲染(去掉吊装特殊逻辑) +- 通行空间以路径点为中心扩展 + +### 3.6 碰撞检测 + +framePosition 即物体中心,现有碰撞盒计算直接正确(无需改动)。 + +--- + +## 四、兼容与迁移 + +### 4.1 旧数据迁移(决策点2 → 方案A) + +**方案A(已确认):自动转换** + +加载旧库时,`IsTwoPointVertical=true` 的吊装路径: +- 转换为 `PathType.Free` +- 路径点坐标直接作为物体几何中心 +- 注意:旧 2 点路径终点是"提升点"(lift 高度),转换时作为物体中心需确认合理性 + +--- + +## 五、实施步骤与进度跟踪 + +| # | 步骤 | 状态 | 备注 | +|----|------|------|------| +| 1 | `PathType` 加 `Free` + `GetDisplayName` | ☐ | | +| 2 | 动画管理器:新增 Free 分支(统一中心对齐 + 方案1姿态) | ☐ | | +| 3 | 渲染插件:Free 普通渲染 | ☐ | | +| 4 | 路径管理器:`StartCreatingNewRoute` 支持 Free | ☐ | | +| 5 | UI:新增自由路径创建入口 | ☐ | PathEditingView + ViewModel | +| 6 | 数据库:枚举扩展(无 schema 变更) | ☐ | | +| 7 | 旧数据迁移(方案A) | ☐ | | +| 8 | 补单测(中心对齐 + 姿态 + 多点) | ☐ | | +| 9 | 编译 + 单测 + 部署 + 手动验证 | ☐ | | + +> 进度图例:☐ 未开始 / 🔄 进行中 / ✅ 完成