# Ground 去 Fragment 依赖实施方案

更新时间：2026-04-08

## 1. 这份方案现在只解决什么

只解决一件事：

- `Ground + 真实物体` 主链里，尽量去掉 `fragment` 参考姿态依赖

只允许改动：

- `PathAnimationManager.cs`
- 必要时补少量日志

明确不做：

- 不新建大范围工具链
- 不改 `Hoisting`
- 不改 `Rail`
- 不重写 `ModelItemTransformHelper`
- 不删除 `RealObjectReferencePoseResolver`
- 不做“整项目去 fragment”

这份方案的目标是：**缩小修改范围，先把 Ground 主链收干净。**

---

## 2. 当前已确认的事实

1. `Ground` 的变换更适合走最简单的宿主增量法：
   - 宿主旋转增量
   - 宿主平移增量
2. `Ground` 这条链不应该再扩散 `local/reference/fragment` 概念。
3. `fragment` 现在的问题，不在于“所有地方都要立刻删”，而在于：
   - Ground 主链还会读它
   - 导致旋转来源不稳定
4. `Ground` 这条链仍然有旋转目标，但这个旋转目标不再来自 `fragment` 参考姿态解释。
5. `Ground` 后续只需要求：
   - 路径在宿主平面里的方向
   - 对应的宿主平面旋转量
6. 也就是说，`Ground` 不再求“reference-based pose”，而只求：
   - `hostForward`
   - `hostUp`
   - `host-planar rotation delta`

---

## 3. 只保留的改造目标

这轮只保留 3 个具体目标：

1. `Ground` 初始化时，不再优先读 fragment 参考姿态
2. `Ground` 平面姿态求解时，不再走 fragment 参考旋转入口，而只求宿主平面旋转量
3. `Ground` 不再允许 fragment planar fallback

只要这 3 点做到，就算这一轮完成。

---

## 4. 当前 Ground 需要处理的入口

### 4.1 初始化入口

当前重点看：

- `SyncTrackedRotationToObjectReference(...)`

要求：

- 当 `PathType == Ground` 且是真实物体时
- 不再去走 `TryCaptureRealObjectReferenceRotation(...)`
- 直接改用当前实际几何姿态，或现有非 fragment 入口
- 这一步的目的不是继续建立另一套“参考姿态定义”，而只是拿到当前增量起点

### 4.2 平面姿态求解入口

当前重点看：

- `TryGetRealObjectReferenceRotation(...)`
- `TryCreateReferenceBasedRealObjectPlanarPoseSolution(...)`

要求：

- `Ground` 不再从这里拿 fragment 参考旋转
- `Ground` 不再继续求 reference-based pose
- `Ground` 只求宿主平面旋转量：
  - 路径 `hostForward`
  - 宿主 `hostUp`
  - 当前对象在宿主坐标系下要追加的平面旋转量

### 4.3 fallback 入口

当前重点看：

- `ShouldAllowFragmentPlanarFallback(PathType pathType)`

要求：

- `Ground` 改成和 `Hoisting` 一样，不再允许 fragment planar fallback

---

## 5. 实施顺序

只按下面顺序做，不扩展：

1. 先改 `Ground` 初始化入口
2. 再改 `Ground` 平面姿态求解入口
3. 再改 `Ground` 尺寸/通行空间入口，避免它们继续偷偷走 `reference-based pose`
4. 最后关掉 `Ground` 的 fragment fallback

每一步都要求：

- 先看日志
- 只改 `Ground`
- 不顺手改别的路径

### 5.1 2026-04-07 夜间分析结论

第一刀已经证明：

- `Ground` 初始化入口可以先切掉 fragment
- 但这还不够

这次日志暴露出的真正问题是：

- `Ground` 虽然不再直接读 fragment
- 但起点姿态求解仍然在走 `TryCreateRealObjectPlanarPoseSolution(...)`
- 也就是仍然在走 `reference-based pose` 入口

所以第二刀必须明确成：

1. `Ground` 不再进入 `TryCreateRealObjectPlanarPoseSolution(...)`
2. `Ground` 起点旋转改成：
   - 当前显示旋转
   - 当前宿主平面 yaw
   - 路径目标宿主平面 yaw
   - 基于这三者直接求目标旋转
3. 也就是 `Ground` 只保留：
   - 当前显示状态作为增量起点
   - 路径方向作为目标方向
   - 宿主平面旋转量作为唯一旋转语义

### 5.2 现有链路与目标链路

当前代码里，`Ground + 真实物体` 至少有 3 个入口会接触姿态：

1. 起点
   - `MoveObjectToPathStart(...)`
   - `TryCreatePlanarPathRotationAtStart(...)`
   - `TryCreateRealObjectPlanarRotationFromHostForward(...)`
2. 逐帧
   - `ApplyGroundAnimationFrame(...)`
3. 尺寸/通行空间
   - `TryCalculateCurrentRealObjectPlanarProjectedExtents(...)`

这一轮的目标链路应该统一成：

1. 初始化
   - 当前显示姿态只用来拿“当前增量起点”
   - 不再把它包装成 `referenceRotation`
2. 起点/逐帧旋转
   - 只求 `hostForward`
   - 只求宿主平面旋转量
   - 不再进入 `TryCreateRealObjectPlanarPoseSolution(...)`
   - 起点应用层不再走 `currentRotation -> targetRotation -> deltaRotation`
   - 改成直接施加宿主轴旋转增量，再补平移把 tracked point 拉回目标点
3. 尺寸/通行空间
   - 对 `Ground` 直接复用固定业务约定：
     - `forward = PositiveX`
     - `up = HostUp`
   - 不再通过 `reference-based pose` 推导 `ModelAxisConvention`

这 3 条链必须保持同一件事：

- `Ground` 不再解释 reference pose
- `Ground` 只解释“当前显示状态 + 路径方向 + 宿主平面旋转量”

---

## 6. 验证标准

这轮不追求“大而全测试矩阵”，只看 3 条：

1. 起点
   - `Ground + 真实物体` 到起点后不再读 fragment 姿态

2. 逐帧
   - `Ground` 播放时旋转来源不再依赖 fragment
   - `Ground` 只根据路径方向继续求宿主平面旋转量

3. 尺寸/通行空间
   - `Ground` 的 projected extents 不再因为 fragment/reference pose 缺失而失败
   - `Ground` 的 `ModelAxisConvention` 不再来自 `TryCreateRealObjectPlanarPoseSolution(...)`

4. fallback
   - `Ground` 关闭 fragment fallback 后，主链要么成功，要么明确报错
   - 不允许再偷偷回退

---

## 7. 当前停止线

如果做到下面这句话，就先停：

- **Ground 主链不再依赖 fragment，但 Hoisting / Rail / 通用参考姿态系统暂时不动。**

不要在这一轮里再继续追求：

- 抽象统一工具类
- 清理全部 reference/local 命名
- 一次性删光 fragment 代码
- 统一三类路径的所有姿态入口

这些都属于下一轮的事。

---

## 8. 2026-04-08 夜间新增：Ground 角度调整的最小实现策略

在 `Ground + 真实物体` 这条新纯增量链上，角度调整不再通过“完整目标姿态重建”实现，而只允许走最单纯的宿主增量法：

1. `up` 轴修正
   - 不单独构造三维姿态
   - 直接并入路径目标 `yaw`
   - `YUp` 取 `YDegrees`
   - `ZUp` 取 `ZDegrees`

2. 非 `up` 轴修正
   - 不与 `yaw` 一次性组合
   - 只在起点落位后，围绕业务跟踪点按宿主轴逐次增量应用
   - 当前约定：
     - `YUp`：应用 `XDegrees`、`ZDegrees`
     - `ZUp`：应用 `XDegrees`、`YDegrees`

3. 逐帧播放
   - 继续只吃“路径宿主平面角 + up 轴修正”
   - 不在每帧重复叠加非 `up` 轴修正
   - 非 `up` 轴修正应由起点姿态一次性建立，并在后续 `yaw` 增量中自然保持

### 明早优先验证

1. `Ground + 真实物体` 到起点
   - 位置是否继续保持正确
   - `X/Y/Z` 角度调整是否真正进入增量旋转链

2. `Ground` 逐帧播放
   - 转弯是否仍保持当前已修好的效果
   - `up` 轴修正是否能跟随路径持续生效

3. 非 `up` 轴修正
   - 是否表现为“起点一次性按宿主轴旋转”
   - 播放过程中不应每帧累加放大