diff --git a/PROJECT_OPTIMIZATION_ANALYSIS.md b/PROJECT_OPTIMIZATION_ANALYSIS.md index e1695852..ed7a7cfe 100644 --- a/PROJECT_OPTIMIZATION_ANALYSIS.md +++ b/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`