refactor: 拆分loadScene流程并更新优化分析

PROJECT_OPTIMIZATION_ANALYSIS.md

@@ -18,7 +18,20 @@
   - `scene/scene_manager_serialization_mixin.py`
   - `scene/scene_manager_model_mixin.py`
 - 效果（本地静态检索）：
-  - 直接访问 `world.interface_manager` / `interface_manager.treeWidget` 已基本移除（仅剩注释或非本轮范围点位）。
+  - 直接访问 `world.interface_manager`: `0`
+  - 直接访问 `interface_manager.treeWidget`: `0`
+  - `app.gui_manager` 仅剩注释引用（`ui/panels/editor_panels_left.py`）
+- Task B 第一轮已落地（`scene_manager_io_mixin.loadScene`）：
+  - 已抽出流程 helper：
+    - `_preflight_load_scene`
+    - `_cleanup_after_failed_load`
+    - `_clear_current_scene_for_load`
+    - `_load_scene_root_from_file`
+    - `_bootstrap_scene_tree_for_loaded_root`
+    - `_load_scene_gui_metadata`
+    - `_retry_load_scene`
+  - `loadScene` 行数：`556 -> 366`
+  - 已清理重复异常分支：`_rebuildParentChildRelationships` 内重复 `except` 已移除
 
 ## 1. 总体画像
 
@@ -82,7 +95,7 @@
 - `ui/panels/editor_panels_right_material.py` (`6`)
 - `ui/panels/editor_panels_left.py` (`5`)
 
-### 2.4 旧上下文耦合集中区
+### 2.4 旧上下文耦合集中区（历史基线，Task A 前）
 
 1. `ui/panels/runtime_actions.py` (`gui_manager=29`)
 2. `core/event_handler.py` (`interface_manager=11`, `gui_manager=11`)
@@ -176,6 +189,76 @@
 - 统一异常日志工具（轻量封装）
 - 首批替换 `animation_tools.py` 与 `property_helpers.py`
 
+## 4.1 本轮深入分析（非 VR，P1 准备）
+
+### A) `scene/scene_manager_io_mixin.py::loadScene`（核心优先）
+
+- 函数规模: `556` 行
+- 近似圈复杂度: `114`
+- 关键问题:
+  - 单函数同时承担 8 类职责（校验/清理/加载/树同步/节点递归处理/脚本恢复/材质恢复/重试）。
+  - 内嵌 `processNode` 递归函数长达 `281` 行，可测试性差。
+  - 调试输出密度高（`print` 与注释 `print` 很多），影响可读性和噪声控制。
+  - `scene/scene_manager_io_mixin.py:1026` 与 `scene/scene_manager_io_mixin.py:1032` 存在重复 `except Exception` 分支（可合并）。
+  - `scene/scene_manager_io_mixin.py:946` 的 GUI 重建入口目前仍注释，行为边界不清晰。
+- 建议拆分（保持外部 API `loadScene` 不变）:
+  - `_preflight_scene_file(filename) -> (ok, normalized_path, reason)`
+  - `_cleanup_before_load(tree_widget, retry_count)`
+  - `_load_bam_scene(filename) -> scene_or_none`
+  - `_bootstrap_tree_items(scene, tree_widget)`
+  - `_walk_loaded_scene(scene, tree_widget) -> loaded_nodes`
+  - `_restore_loaded_nodes_state(node_path, processed_lights, loaded_nodes)`（从 `processNode` 中抽）
+  - `_post_load_finalize(scene, loaded_nodes, filename)`
+  - `_retry_load_scene(filename, retry_count, error) -> bool`
+- 验收标准:
+  - `loadScene` 主体压缩到 `120` 行以内，只保留流程编排。
+  - 节点恢复行为（位置/材质/脚本/可见性）与当前一致。
+  - 失败重试逻辑保持语义一致。
+- 当前状态（2026-02-28）:
+  - 第一轮已完成（预检/清理/加载/树初始化/GUI元数据/重试）。
+  - 剩余主要体积来自内嵌 `processNode`，下一轮应继续提取为独立方法。
+
+### B) `main.py::__init__`（第二优先）
+
+- 函数规模: `375` 行
+- 近似圈复杂度: `15`
+- 问题性质:
+  - 复杂度不高，但“启动装配职责”过于集中，初始化顺序风险高。
+- 建议拆分:
+  - `_init_legacy_compat_fields()`
+  - `_init_core_services_non_vr()`（不含 VR）
+  - `_init_imgui_runtime()`
+  - `_init_panel_modules()`
+  - `_init_runtime_state_flags()`
+  - `_bind_input_shortcuts()`
+  - `_init_drag_drop_and_messages()`
+- 约束:
+  - VR 初始化保持原样，不纳入本轮改造范围。
+
+### C) `ui/panels/animation_tools.py::_getActor`（第三优先）
+
+- 函数规模: `510` 行
+- 近似圈复杂度: `143`
+- 关键问题:
+  - 路径推断、缓存策略、Actor 构建、autoBind 回退、GLTF 特化混在一个函数中。
+  - 局部嵌套函数层级深，行为分支很难覆盖测试。
+- 建议拆分:
+  - `_resolve_actor_owner_and_paths(origin_model)`
+  - `_load_actor_from_candidate_paths(owner_model, paths)`
+  - `_load_actor_via_memory_fallback(owner_model, origin_model)`
+  - `_load_actor_via_gltf_special(path)`
+  - `_validate_actor_playable(actor_or_proxy)`
+  - `_cache_actor(owner_model, actor)`
+- 验收标准:
+  - `_getActor` 保留为流程入口，长度控制到 `150` 行以内。
+  - 保持当前“优先路径加载，失败回退内存/autoBind”的策略不变。
+
+## 4.2 Task B 执行顺序建议（非 VR）
+
+1. 先拆 `loadScene`（收益最大，且与 VR 无关）。
+2. 再整理 `main.__init__`（降低后续模块接入冲突）。
+3. 最后处理 `_getActor`（风险最高，建议独立提交并做手工回归）。
+
 ## 5. 与现有文档关系
 
 - 模块总索引: `PROJECT_MODULE_INDEX.md`