360 lines
13 KiB
Markdown
360 lines
13 KiB
Markdown
# PROJECT_OPTIMIZATION_ANALYSIS
|
||
|
||
> 基于本地代码静态扫描生成（不含远程仓库信息，不含 `RenderPipelineFile/` 第三方目录）。
|
||
|
||
- 分析时间: 2026-03-01
|
||
- 扫描范围: `main.py`, `Start_Run.py`, `core/`, `scene/`, `project/`, `ui/`, `ssbo_component/`, `TransformGizmo/`, `scripts/`, `tools/`, `templates/`
|
||
|
||
## 0. 执行进展（非 VR）
|
||
|
||
- 已完成 `EditorContext` 适配层：`core/editor_context.py`
|
||
- 已接入文件：
|
||
- `core/event_handler.py`
|
||
- `core/selection.py`
|
||
- `core/InfoPanelManager.py`
|
||
- `ui/panels/runtime_actions.py`
|
||
- `core/terrain_manager.py`
|
||
- `scene/scene_manager_convert_tiles_mixin.py`
|
||
- `scene/scene_manager_serialization_mixin.py`
|
||
- `scene/scene_manager_model_mixin.py`
|
||
- 效果（本地静态检索）：
|
||
- 直接访问 `world.interface_manager`: `0`
|
||
- 直接访问 `interface_manager.treeWidget`: `0`
|
||
- 旧上下文引用已从“接口访问路径”转为“上下文适配层/兼容字段”模式
|
||
- 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`
|
||
- `_walk_loaded_scene`
|
||
- `_process_loaded_scene_node`
|
||
- `_restore_node_scripts`
|
||
- `_parse_vec3_string`
|
||
- `_parse_color_string`
|
||
- `loadScene` 行数：`556 -> 74`
|
||
- 已清理重复异常分支：`_rebuildParentChildRelationships` 内重复 `except` 已移除
|
||
- `main.py::__init__` 第一轮拆分已落地（非 VR）：
|
||
- `__init__` 行数：`375 -> 27`
|
||
- 已抽出初始化阶段方法：
|
||
- `_configure_main_window`
|
||
- `_init_legacy_compat_fields`
|
||
- `_init_core_services_non_vr`
|
||
- `_init_runtime_features_non_vr`
|
||
- `_init_imgui_runtime`
|
||
- `_init_panel_modules`
|
||
- `_init_startup_fonts`
|
||
- `_init_ui_runtime_state`
|
||
- `_bind_runtime_events`
|
||
- `_finalize_startup`
|
||
- 本轮新增深入分析结论（非 VR）：
|
||
- `ui/panels/animation_tools.py::_getActor` 第一轮拆分已完成
|
||
- 实测指标：`510 -> 39` 行，近似圈复杂度 `191 -> 15`，内嵌局部函数 `9 -> 0`
|
||
- `core/selection.py::updateGizmoDrag` 第一轮拆分已完成：
|
||
- 实测指标：`278 -> 32` 行，近似圈复杂度 `65 -> 10`
|
||
- 缩放/旋转/平移逻辑已拆到独立 helper
|
||
- `ui/LUI/lui_manager_interaction.py::_update_drag` 第一轮拆分已完成：
|
||
- 实测指标：`348 -> 28` 行，近似圈复杂度 `79 -> 7`
|
||
- Canvas/组件拖拽流程已拆到独立 helper
|
||
- `ui/panels/editor_panels_left.py::_draw_resource_manager` 保留布局版拆分已完成：
|
||
- 实测指标：`310 -> 23` 行（第一轮 `310 -> 163`，第二轮 `163 -> 23`）
|
||
- 目录/文件项渲染、展开内容、右键菜单流程已拆到独立 helper
|
||
|
||
## 1. 总体画像
|
||
|
||
- Python 文件: `147`
|
||
- 代码总行数: `58,341`
|
||
- `except Exception` / `except:` 总计: `949`
|
||
- 裸 `except:` 总计: `62`
|
||
- 旧上下文关键词引用总量:
|
||
- `interface_manager`: `20`
|
||
- `treeWidget`: `2`
|
||
- `gui_manager`: `90`
|
||
|
||
结论:
|
||
|
||
- Qt 依赖已清理后，当前主要技术债集中在三类:
|
||
- 过大函数（可维护性差）
|
||
- 异常处理过宽（问题可观测性差）
|
||
- 旧 GUI 上下文命名耦合（边界不清晰）
|
||
|
||
## 2. 热点文件（按规模/风险）
|
||
|
||
### 2.1 超大文件 Top（非 VR）
|
||
|
||
1. `core/selection.py` (`2941` 行)
|
||
2. `core/InfoPanelManager.py` (`1725` 行)
|
||
3. `ui/LUI/lui_manager_editor.py` (`1724` 行)
|
||
4. `ui/panels/property_helpers.py` (`1711` 行)
|
||
5. `ui/LUI/lui_function_properties.py` (`1707` 行)
|
||
6. `TransformGizmo/rotate_gizmo.py` (`1587` 行)
|
||
7. `ui/panels/animation_tools.py` (`1579` 行)
|
||
8. `templates/main_template.py` (`1571` 行)
|
||
|
||
### 2.2 长函数 Top（优先拆分，非 VR 当前状态）
|
||
|
||
1. `ui/LUI/lui_function_properties.py::_draw_component_properties` (`1441` 行)
|
||
2. `ui/LUI/lui_manager_interaction.py::_handle_resize_drag` (`257` 行)
|
||
3. `ui/LUI/lui_manager_editor.py::_set_parent_child_relationship` (`234` 行)
|
||
4. `ui/panels/editor_panels_top.py::draw_menu_bar` (`227` 行)
|
||
5. `scene/scene_manager_io_mixin.py::saveScene` (`222` 行)
|
||
6. `TransformGizmo/move_gizmo.py::_on_mouse_down` (`222` 行)
|
||
7. `ui/LUI/lui_manager_editor.py::draw_editor` (`217` 行)
|
||
|
||
### 2.3 异常处理密度高（可观测性风险）
|
||
|
||
1. `ui/panels/animation_tools.py` (`except* = 85`)
|
||
2. `core/selection.py` (`56`)
|
||
3. `ui/panels/property_helpers.py` (`54`)
|
||
4. `templates/main_template.py` (`39`)
|
||
5. `scene/scene_manager_model_mixin.py` (`36`)
|
||
6. `ui/LUI/lui_function_properties.py` (`36`)
|
||
7. `ui/LUI/lui_manager_editor.py` (`33`)
|
||
8. `core/world.py` (`28`)
|
||
9. `scene/scene_manager_serialization_mixin.py` (`27`)
|
||
|
||
裸 `except:` 集中区:
|
||
|
||
- `core/selection.py` (`7`)
|
||
- `scene/scene_manager_model_mixin.py` (`7`)
|
||
- `ui/panels/editor_panels_right_material.py` (`6`)
|
||
- `ui/panels/editor_panels_left.py` (`5`)
|
||
|
||
### 2.4 旧上下文耦合集中区（当前分布，非 VR）
|
||
|
||
1. `ui/panels/runtime_actions.py` (`gui_manager=25`)
|
||
2. `core/event_handler.py` (`interface_manager=7`, `gui_manager=13`)
|
||
3. `ui/panels/editor_panels_right.py` (`gui_manager=18`)
|
||
4. `scene/scene_manager_serialization_mixin.py` (`gui_manager=13`)
|
||
5. `scene/scene_manager_model_mixin.py` (`interface_manager=6`)
|
||
6. `ui/panels/editor_panels_left.py` (`gui_manager=5`)
|
||
7. `ui/panels/interaction_panels.py` (`gui_manager=5`)
|
||
|
||
## 3. 优化优先级（建议执行顺序）
|
||
|
||
## P0: 上下文收敛（已完成主干，继续收尾）
|
||
|
||
目标: 统一 GUI/场景树访问边界，减少跨模块 `hasattr(..., 'interface_manager')` 与 `treeWidget` 语义残留。
|
||
|
||
当前状态:
|
||
|
||
1. `EditorContext` 已落地并完成第一批接入。
|
||
2. 仍有 `gui_manager/interface_manager` 兼容字段引用集中在少量模块。
|
||
|
||
建议动作（收尾）:
|
||
|
||
1. 将 `runtime_actions` 与 `editor_panels_right` 中 `gui_manager` 读写统一迁移到 `editor_context` 访问方法。
|
||
2. 给 `event_handler` 与 `scene_manager_serialization_mixin` 增加“兼容字段缺失”单点兜底函数，移除重复 `hasattr` 防御分支。
|
||
3. 文档层明确“兼容字段仅保留读，不再新增写路径”。
|
||
|
||
预期收益:
|
||
|
||
- 降低命名残留与多处 `hasattr` 防御代码。
|
||
- 后续模块拆分时边界更稳定。
|
||
|
||
## P1: 大函数拆分（第二阶段）
|
||
|
||
目标: 将核心长函数拆分成“流程编排 + 子步骤函数”，减少单函数认知负担。
|
||
|
||
建议拆分顺序（非 VR 当前阶段）:
|
||
|
||
1. `ui/LUI/lui_function_properties.py::_draw_component_properties`（可按“变换/布局/视觉/交互/脚本”分区）
|
||
2. `ui/LUI/lui_manager_interaction.py::_handle_resize_drag`
|
||
3. `ui/panels/editor_panels_top.py::draw_menu_bar`
|
||
|
||
预期收益:
|
||
|
||
- 回归问题定位更快。
|
||
- 面板和场景加载逻辑更易测试。
|
||
|
||
## P2: 异常处理治理（并行推进）
|
||
|
||
目标: 将“吞异常”改为“有边界的降级 + 可追踪日志”。
|
||
|
||
建议规则:
|
||
|
||
1. 禁止新增裸 `except:`。
|
||
2. 高风险路径必须记录上下文:
|
||
- 节点名/资源路径/操作类型/当前工具状态
|
||
3. 对可恢复错误使用 `warning`，不可恢复错误返回显式失败值。
|
||
|
||
优先文件:
|
||
|
||
- `ui/panels/animation_tools.py`
|
||
- `core/selection.py`
|
||
- `ui/panels/property_helpers.py`
|
||
- `scene/scene_manager_io_mixin.py`
|
||
|
||
## 4. 下一步可直接执行的任务包
|
||
|
||
### Task A（已完成）
|
||
|
||
- 建立 `core/editor_context.py`（或同级命名）
|
||
- 给 `event_handler/selection/InfoPanelManager/runtime_actions` 接入上下文
|
||
- 保持外部 API 不变，仅替换内部访问路径
|
||
|
||
### Task B（已完成）
|
||
|
||
- 重构 `scene_manager_io_mixin.loadScene`：
|
||
- `preflight`
|
||
- `clear_old_scene`
|
||
- `load_bam`
|
||
- `rebuild_scene_tree`
|
||
- `post_load_sync`
|
||
|
||
### Task C（待执行，1 天）
|
||
|
||
- 统一异常日志工具（轻量封装）
|
||
- 首批替换 `animation_tools.py` 与 `property_helpers.py`
|
||
|
||
### Task D（已完成，第一轮）
|
||
|
||
- 重构 `ui/panels/animation_tools.py::_getActor`：
|
||
- `resolve_owner_and_model_path_tags`
|
||
- `validate_or_evict_cached_actor`
|
||
- `build_candidate_paths`
|
||
- `try_actor_from_path`
|
||
- `try_actor_from_memory`
|
||
- `cache_and_tag_actor`
|
||
- 验收:
|
||
- `_getActor` 长度降到 `<= 170` 行（实际 `39` 行）
|
||
- 保持“文件路径优先，内存 autoBind 兜底”语义一致
|
||
- 不改 VR 逻辑
|
||
|
||
### Task E（已完成，第一轮）
|
||
|
||
- 拆分 `core/selection.py::updateGizmoDrag`：
|
||
- `_apply_scale_drag`
|
||
- `_apply_rotation_drag`
|
||
- `_compute_axis_movement_distance`
|
||
- `_apply_translation_drag`
|
||
- 验收:
|
||
- 主函数长度降到 `<= 120` 行（实际 `32` 行）
|
||
- 保持当前 gizmo 拖拽行为一致
|
||
|
||
### Task F（已完成，保留布局版两轮）
|
||
|
||
- 拆分 `ui/panels/editor_panels_left.py::_draw_resource_manager`
|
||
- 验收:
|
||
- 主函数长度降到 `<= 160` 行（第一轮 `163` 行，第二轮 `23` 行）
|
||
- 保持原有布局/样式/文案/交互顺序不变
|
||
|
||
### Task G（已完成，第一轮）
|
||
|
||
- 拆分 `ui/LUI/lui_manager_interaction.py::_update_drag`
|
||
- 验收:
|
||
- 主函数长度降到 `<= 140` 行（实际 `28` 行）
|
||
- 拖拽与缩放交互行为保持一致
|
||
|
||
### Task H（推荐下一步，2-3 天）
|
||
|
||
- 拆分 `ui/LUI/lui_function_properties.py::_draw_component_properties`
|
||
- 验收:
|
||
- 主函数长度降到 `<= 260` 行
|
||
- 按“变换/布局/视觉/交互/脚本”子区块拆分并保持渲染逻辑一致
|
||
|
||
## 4.1 本轮深入分析（非 VR，P1 准备）
|
||
|
||
### A) `scene/scene_manager_io_mixin.py::loadScene`（核心优先，已完成）
|
||
|
||
- 函数规模: `74` 行（重构前 `556` 行）
|
||
- 近似圈复杂度（重构前）: `114`
|
||
- 关键问题:
|
||
- `processNode` 内联逻辑已外提为 `_walk_loaded_scene/_process_loaded_scene_node`。
|
||
- 重复异常分支已清理。
|
||
- 仍存在较多调试输出（`print` 与注释 `print`），后续可做日志分级。
|
||
- 建议拆分（保持外部 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-03-01）:
|
||
- 第二轮已完成（`loadScene` 已达验收目标：`74` 行）。
|
||
- 后续建议转入回归观察，优先推进 `ui/LUI/lui_function_properties.py::_draw_component_properties`。
|
||
|
||
### B) `main.py::__init__`（第二优先，已完成第一轮）
|
||
|
||
- 函数规模: `27` 行（重构前 `375` 行）
|
||
- 状态:
|
||
- 初始化编排已拆分为阶段方法，VR 初始化逻辑保持原样。
|
||
- 约束:
|
||
- 后续仅建议做微调，不再进行结构性拆分。
|
||
|
||
### C) `ui/panels/animation_tools.py::_getActor`（已完成第一轮）
|
||
|
||
- 函数规模: `39` 行（重构前 `510` 行）
|
||
- 近似圈复杂度: `15`（重构前 `191`）
|
||
- 已落地 helper:
|
||
- `_sync_owner_model_path_tags`
|
||
- `_get_valid_cached_actor`
|
||
- `_detect_animation_nodes`
|
||
- `_collect_autobind_source_candidates`
|
||
- `_try_memory_fallback_actor`
|
||
- `_collect_actor_candidate_paths`
|
||
- `_try_actor_from_path`
|
||
- 状态:
|
||
- 入口函数已收敛为流程编排。
|
||
- 已通过 `python -m compileall ui/panels/animation_tools.py`。
|
||
|
||
### D) `core/selection.py::updateGizmoDrag`（已完成第一轮）
|
||
|
||
- 函数规模: `32` 行（重构前 `278` 行）
|
||
- 近似圈复杂度: `10`（重构前 `65`）
|
||
- 已落地 helper:
|
||
- `_validate_gizmo_drag_state`
|
||
- `_apply_scale_drag`
|
||
- `_apply_rotate_drag`
|
||
- `_compute_axis_movement_distance`
|
||
- `_apply_translate_drag`
|
||
- 状态:
|
||
- 主流程已收敛为编排入口。
|
||
- 已通过 `python -m compileall core/selection.py`。
|
||
|
||
### E) `ui/panels/editor_panels_left.py::_draw_resource_manager`（已完成两轮）
|
||
|
||
- 函数规模: `23` 行（重构前 `310` 行）
|
||
- 近似圈复杂度: 已由主函数分支链路转移到子流程函数（入口仅保留编排）
|
||
- 已落地 helper:
|
||
- `_update_resource_manager_window_rect`
|
||
- `_draw_resource_toolbar_and_filters`
|
||
- `_draw_resource_directory_entries`
|
||
- `_draw_resource_directory_entry`
|
||
- `_draw_resource_directory_children`
|
||
- `_draw_resource_subdir_entry`
|
||
- `_draw_resource_subfile_entry`
|
||
- `_draw_resource_file_entries`
|
||
- `_draw_resource_file_entry`
|
||
- `_draw_resource_context_menu`
|
||
- 状态:
|
||
- 主流程已收敛为编排入口，且保持原布局与交互顺序。
|
||
- 已通过 `python -m compileall ui/panels/editor_panels_left.py`。
|
||
|
||
## 4.2 执行顺序建议（非 VR）
|
||
|
||
1. `loadScene` 已完成两轮拆分（当前建议冻结并转入回归观察）。
|
||
2. `main.__init__` 已完成第一轮拆分（建议转入回归观察）。
|
||
3. `_update_drag` 已完成第一轮拆分，建议转入回归观察。
|
||
4. 下一步处理 `_draw_component_properties`（属性面板分区拆分）。
|
||
5. 然后处理 `_handle_resize_drag`（拖拽缩放路径补充拆分）。
|
||
|
||
## 5. 与现有文档关系
|
||
|
||
- 模块总索引: `PROJECT_MODULE_INDEX.md`
|
||
- 项目任务清单: `PROJECT_TASK_CHECKLIST.md`
|
||
- 历史分析: `IMGUI_MODULE_ANALYSIS.md`
|
||
|
||
---
|
||
|
||
如果按此路线继续，建议下一轮直接从 **Task H** 开始，先落地 `_draw_component_properties` 的分区拆分并保持行为不变。
|