Refine scene view gizmo execution plan

docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md

@@ -808,3 +808,199 @@ ISceneViewportGizmoProvider
 - Phase 1：已完成
 - Phase 2：已完成并收口
 - Phase 3 及后续阶段：仍待继续推进
+
+---
+
+## 12. 下一阶段执行计划 2026-04-03
+
+基于当前真实代码状态，下一阶段不应继续直接堆叠新 gizmo 功能，而应优先完成 `Phase 3: Gizmo Provider Registry`。当前最主要的结构性问题有三处：
+
+1. `SceneViewportOverlayBuilder` 仍是大单体
+   - camera gizmo
+   - light gizmo
+   - scene icon / frustum / helper 生成逻辑仍堆在同一处
+
+2. `SceneViewPanel` 仍参与 transform gizmo 的 transient overlay 注入
+   - 仍通过 `SetSceneViewTransientTransformGizmoOverlayData(...)` 把临时 frame data 注入宿主
+   - 这说明 transform gizmo 还没有真正并入正式 provider 体系
+
+3. `OrientationGizmo` 仍属于 HUD/ImGui 历史链路
+   - 现在功能上可用
+   - 但尚未在架构层被正式命名为 HUD overlay
+
+因此，下一阶段推荐拆成如下 4 个可执行小阶段。
+
+### 12.1 Phase 3A：Overlay Provider Registry 落地
+
+目标：
+- 把“谁负责生成 SceneView world overlay”从 `SceneViewportOverlayBuilder` 中拆出
+- 让 `builder` 退化成聚合器，而不是所有 gizmo 规则的实现者
+
+本阶段应新增：
+- `ISceneViewportOverlayProvider`
+- `SceneViewportOverlayProviderRegistry`
+- `SceneViewportOverlayBuildContext`
+
+本阶段应先拆出的 provider：
+- `SceneViewportCameraOverlayProvider`
+- `SceneViewportLightOverlayProvider`
+
+本阶段不应做：
+- 不修改 gizmo 样式
+- 不动 transform gizmo 交互算法
+- 不改 orientation gizmo
+
+完成标志：
+- `SceneViewportOverlayBuilder` 不再直接内嵌 camera/light 具体生成逻辑
+- provider 可以按顺序注册并聚合输出 `SceneViewportOverlayFrameData`
+- SceneView 现有 camera/light 图标、frustum、directional light helper 视觉结果保持不变
+
+建议测试：
+- provider registry 装配顺序测试
+- camera provider contract 测试
+- light provider contract 测试
+- 现有 overlay render flow 测试继续通过
+
+### 12.2 Phase 3B：Transform Gizmo 并入正式 Provider 体系
+
+目标：
+- 去掉当前的 transient gizmo overlay 桥接层
+- 让 move / rotate / scale gizmo 和其他 SceneView overlay 一样，成为正式 provider 输出
+
+本阶段应处理：
+- `SceneViewPanel` 中 gizmo frame 组织逻辑
+- `ViewportHostService` 中的 transient overlay 存储字段
+- `SceneViewportTransformGizmoFrameBuilder`
+
+建议方向：
+- 引入 `SceneViewportTransformGizmoOverlayProvider`
+- provider 输入来自统一的 gizmo state / selection state / camera state
+- 输出仍然是统一的 `worldLines / screenTriangles / handleRecords`
+
+本阶段完成后，应删除或废弃：
+- `SetSceneViewTransientTransformGizmoOverlayData(...)`
+- `m_sceneViewTransientTransformGizmoOverlay`
+- `m_sceneViewTransientTransformGizmoInputs`
+
+完成标志：
+- `SceneViewPanel` 不再向宿主注入临时 gizmo overlay 数据
+- `ViewportHostService` 只消费正式 overlay provider 输出
+- move / rotate / scale gizmo 交互行为不回退
+
+建议测试：
+- move/rotate/scale gizmo provider 输出测试
+- overlay handle hit test 回归测试
+- SceneView render plan 下 gizmo 仍能正常显示与拾取
+
+### 12.3 Phase 4：HUD Overlay 与 World Overlay 正式分层
+
+目标：
+- 把当前“能工作但还没正式命名”的 HUD 链路正规化
+- 明确区分 `world overlay` 与 `HUD overlay`
+
+本阶段应做：
+- 保留 `SceneViewportEditorOverlayPass` 作为 world overlay GPU pass
+- 将 `SceneViewportOverlayRenderer` 明确归类为 HUD overlay renderer
+- 将 `OrientationGizmo` 明确纳入 HUD overlay 体系
+
+本阶段之后的职责边界应为：
+- `world overlay`
+  - scene icon
+  - camera frustum
+  - light helper
+  - transform gizmo
+- `HUD overlay`
+  - orientation gizmo
+  - Scene toolbar
+  - 后续 label / hint / debug text
+
+完成标志：
+- world/HUD 两条链路命名清楚
+- orientation gizmo 不再被视为历史遗留杂项
+- 后续 HUD 元素可持续接入，而不再向 world overlay 污染
+
+建议测试：
+- HUD overlay 独立渲染入口测试
+- SceneView panel 中 HUD/world 顺序与命中关系测试
+
+### 12.4 Phase 5：Editor Gizmo 资源体系继续收口
+
+目标：
+- 继 shader 之后，把 gizmo 相关 editor 资源定位逻辑继续集中
+
+本阶段建议新增：
+- `SceneViewportResourcePaths` 或等价 editor resource locator
+
+本阶段应纳入统一入口的内容：
+- gizmo shader 路径
+- camera/light icon 路径
+- 后续如果引入 mesh/wire helper 资源，也走同一入口
+
+本阶段不要求：
+- 不必立刻做 atlas
+- 不必引入复杂资源注册中心
+
+完成标志：
+- panel/pass 内不再到处手写 `exeDir/../../resources/...`
+- editor 资源定位逻辑集中，便于后续 packaging 与迁移
+
+建议测试：
+- 资源路径解析测试
+- working directory 改变后的 editor 资源加载测试
+
+### 12.5 Phase 6：测试与打包边界收口
+
+目标：
+- 把当前已经成型的边界真正测住
+
+需要补齐的关键测试类别：
+
+1. provider contract
+   - provider 输入什么
+   - 必须输出什么
+   - 禁止输出什么
+
+2. render assembly contract
+   - SceneView render plan 如何装配 post-scene / overlay / HUD
+
+3. resource boundary
+   - editor-only shader / icon 不污染 runtime builtin
+   - player/runtime 构建不依赖 SceneView 专属资源
+
+4. interaction regression
+   - gizmo handle hit test
+   - scene icon picking
+   - HUD 与 world overlay 的点击优先级
+
+完成标志：
+- 当前 plan 第 9 节中的 7 条完成态判定标准全部可被验证
+
+### 12.6 推荐执行顺序
+
+严格建议按下面顺序推进，不要跳阶段：
+
+1. Phase 3A
+2. Phase 3B
+3. Phase 4
+4. Phase 5
+5. Phase 6
+
+原因：
+- 先做 provider 化，才能消除 `builder` 与 `SceneViewPanel` 的持续膨胀
+- 先做 transform gizmo provider 化，后面 HUD/world 分层才不会再被临时桥接逻辑牵制
+- 资源与测试应在结构稳定后统一收口，而不是提前做成半成品
+
+### 12.7 下一次会话的直接开工点
+
+下一次正式实施时，优先执行 `Phase 3A`，并以如下拆分作为第一批提交目标：
+
+1. 新建 `ISceneViewportOverlayProvider`
+2. 新建 `SceneViewportOverlayProviderRegistry`
+3. 抽离 `SceneViewportCameraOverlayProvider`
+4. 抽离 `SceneViewportLightOverlayProvider`
+5. 让 `SceneViewportOverlayBuilder` 改为只负责：
+   - 构建上下文
+   - 调用 provider registry
+   - 合并 `SceneViewportOverlayFrameData`
+
+这一步完成后，当前 SceneView gizmo 系统才算真正进入“可持续扩展”的第二阶段。