Rowland/EG

Fork 1

ayuan9957 c8eb4cef4d refactor(lui): complete batch split for interaction/editor/property flows

2026-03-01 19:39:13 +08:00

20 KiB

Raw Blame History

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
ui/LUI/lui_function_properties.py::_draw_component_properties 第一轮编排拆分已完成：
- 实测指标：1441 -> 3 行（入口）
- 新增编排/子流程 helper：
  - _draw_component_properties_core（34）
  - _draw_text_and_button_properties（216）
  - _draw_layout_transform_properties（200）
  - _draw_type_specific_properties（835）
  - _draw_anchor_and_hierarchy_properties（168）
ui/LUI/lui_manager_interaction.py::_handle_resize_drag 第二轮拆分已完成：
- 实测指标：257 -> 3 行（入口）
- 新增编排/子流程 helper：
  - _handle_resize_drag_core（44）
  - _finish_resize_drag_if_released（19）
  - _compute_resize_drag_bounds（109）
  - _apply_resize_drag_updates（110）
ui/LUI/lui_manager_interaction.py::_compute_resize_drag_bounds / _apply_resize_drag_updates 第三轮细拆已完成：
- 实测指标：109 -> 27 / 110 -> 21
- 新增细粒度 helper（边界计算与组件应用分层）：
  - _get_resize_start_values（7）
  - _apply_resize_handle_delta（36）
  - _apply_resize_min_size_clamp（15）
  - _apply_shift_keep_ratio_resize（17）
  - _apply_alt_center_resize（22）
  - _resolve_resize_parent_context（13）
  - _apply_resize_component_size_by_type（24）
  - _sync_input_field_layout_stretch（22）
ui/LUI/lui_function_properties.py::_draw_type_specific_properties 第二轮拆分已完成：
- 实测指标：835 -> 25 行（类型分发入口）
- 新增类型 helper：
  - _draw_type_props_input_field（91）
  - _draw_type_props_slider（11）
  - _draw_type_props_checkbox（19）
  - _draw_type_props_plane_image（152）
  - _draw_type_props_frame（14）
  - _draw_type_props_selectbox（84）
  - _draw_type_props_http_text（72）
  - _draw_type_props_video（10）
  - _draw_video_source_and_audio_controls（4，第三轮后为编排入口）
  - _draw_video_playback_controls（147）
ui/LUI/lui_function_properties.py::_draw_video_source_and_audio_controls 第三轮拆分已完成：
- 实测指标：231 -> 4 行（入口）
- 新增子流程 helper：
  - _draw_video_audio_controls（26）
  - _draw_video_source_controls（19）
  - _process_pending_video_source（22）
  - _load_video_texture_from_source（21）
  - _apply_loaded_video_texture（14）
  - _sync_video_size_and_sprite（28）
  - _replace_video_sprite（23）
  - _refresh_video_keep_alive_node（22）
  - _load_audio_for_component（22）
  - _start_video_texture_playback（7）
ui/LUI/lui_function_properties.py::_draw_text_and_button_properties 第四轮拆分已完成：
- 实测指标：216 -> 14 行（入口）
- 新增子流程 helper（文本编辑/颜色同步/按钮贴图）：
  - _draw_text_content_editor（13）
  - _draw_text_font_size_editor（18）
  - _draw_text_color_editor（11）
  - _sync_text_or_button_color（10）
  - _draw_button_texture_controls（19）
  - _apply_button_texture_variant（28）
ui/LUI/lui_manager_editor.py::_set_parent_child_relationship 第四轮拆分已完成：
- 实测指标：234 -> 43 行（入口）
- 新增子流程 helper（关系校验/索引同步/可见层级）：
  - _is_valid_relationship_index（5）
  - _prepare_parent_child_link（8）
  - _remove_child_from_old_parent（8）
  - _attach_child_to_new_parent（6）
  - _compute_new_child_local_position（7）
  - _ensure_child_visibility_and_layer（19）
ui/LUI/lui_function_properties.py::_draw_layout_transform_properties 第四轮拆分已完成：
- 实测指标：200 -> 10 行（入口）
- 新增子流程 helper（填充模式/尺寸联动/Layout Group/Z-Offset）：
  - _draw_fill_layout_controls（37）
  - _draw_position_controls（18）
  - _draw_size_controls（17）
  - _draw_layout_group_controls（53）
  - _draw_z_offset_controls（27）

1. 总体画像

Python 文件: 147
代码总行数: 58,479
except Exception / except: 总计: 993
裸 except: 总计: 52
旧上下文关键词引用总量:
- interface_manager: 20
- treeWidget: 2
- gui_manager: 90

结论:

Qt 依赖已清理后，当前主要技术债集中在三类:
- 过大函数（可维护性差）
- 异常处理过宽（问题可观测性差）
- 旧 GUI 上下文命名耦合（边界不清晰）

2. 热点文件（按规模/风险）

2.1 超大文件 Top（非 VR）

core/selection.py (2933 行)
ui/LUI/lui_function_properties.py (1731 行)
core/InfoPanelManager.py (1726 行)
ui/LUI/lui_manager_editor.py (1725 行)
ui/panels/property_helpers.py (1712 行)
TransformGizmo/rotate_gizmo.py (1588 行)
templates/main_template.py (1572 行)
ui/panels/animation_tools.py (1563 行)

2.2 长函数 Top（优先拆分，非 VR 当前状态）

ui/panels/editor_panels_top.py::draw_menu_bar (227 行)
scene/scene_manager_io_mixin.py::saveScene (222 行)
TransformGizmo/move_gizmo.py::_on_mouse_down (222 行)
ui/LUI/lui_manager_editor.py::draw_editor (217 行)
ui/LUI/lui_manager_editor.py::draw_component_tree (217 行)
core/InfoPanelManager.py::add_methods_to_property_panel (209 行)
ui/panels/editor_panels_right.py::_draw_animation_properties (201 行)
ui/panels/editor_panels_right.py::_draw_gui_properties (191 行)
core/event_handler.py::mousePressEventLeft (186 行)
scene/scene_manager_model_mixin.py::importModel (177 行)

2.3 异常处理密度高（可观测性风险）

ui/panels/animation_tools.py (except* = 85)
core/selection.py (56)
ui/panels/property_helpers.py (54)
templates/main_template.py (39)
scene/scene_manager_model_mixin.py (36)
ui/LUI/lui_function_properties.py (36)
ui/LUI/lui_manager_editor.py (33)
core/world.py (28)
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）

ui/panels/runtime_actions.py (gui_manager=25)
core/event_handler.py (interface_manager=7, gui_manager=13)
ui/panels/editor_panels_right.py (gui_manager=18)
scene/scene_manager_serialization_mixin.py (gui_manager=13)
scene/scene_manager_model_mixin.py (interface_manager=6)
ui/panels/editor_panels_left.py (gui_manager=5)
ui/panels/interaction_panels.py (gui_manager=5)

3. 优化优先级（建议执行顺序）

P0: 上下文收敛（已完成主干，继续收尾）

目标: 统一 GUI/场景树访问边界，减少跨模块 hasattr(..., 'interface_manager') 与 treeWidget 语义残留。

当前状态:

EditorContext 已落地并完成第一批接入。
仍有 gui_manager/interface_manager 兼容字段引用集中在少量模块。

建议动作（收尾）:

将 runtime_actions 与 editor_panels_right 中 gui_manager 读写统一迁移到 editor_context 访问方法。
给 event_handler 与 scene_manager_serialization_mixin 增加“兼容字段缺失”单点兜底函数，移除重复 hasattr 防御分支。
文档层明确“兼容字段仅保留读，不再新增写路径”。

预期收益:

降低命名残留与多处 hasattr 防御代码。
后续模块拆分时边界更稳定。

P1: 大函数拆分（第二阶段）

目标: 将核心长函数拆分成“流程编排 + 子步骤函数”，减少单函数认知负担。

建议拆分顺序（非 VR 当前阶段）:

ui/panels/editor_panels_top.py::draw_menu_bar
scene/scene_manager_io_mixin.py::saveScene
core/InfoPanelManager.py::add_methods_to_property_panel

预期收益:

回归问题定位更快。
面板和场景加载逻辑更易测试。

P2: 异常处理治理（并行推进）

目标: 将“吞异常”改为“有边界的降级 + 可追踪日志”。

建议规则:

禁止新增裸 except:。
高风险路径必须记录上下文:
- 节点名/资源路径/操作类型/当前工具状态
对可恢复错误使用 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（已完成，第一轮）

拆分 ui/LUI/lui_function_properties.py::_draw_component_properties
验收:
- 主函数长度降到 <= 260 行（实际 3 行，编排核心 34 行）
- 已完成第一轮分区拆分并保持渲染逻辑一致

Task I（已完成，第二轮）

拆分 ui/LUI/lui_manager_interaction.py::_handle_resize_drag
验收:
- 入口流程收敛到 <= 120 行（实际 3 行，编排核心 44 行）
- 缩放手柄行为与边界语义保持一致
第三轮细拆补充（已完成）:
- _compute_resize_drag_bounds: 109 -> 27
- _apply_resize_drag_updates: 110 -> 21
- 继续保持缩放语义一致

Task J（已完成，第二轮）

继续拆分 ui/LUI/lui_function_properties.py::_draw_type_specific_properties
验收:
- 单函数长度降到 <= 320 行（实际 25 行）
- 按组件类型拆分为独立 helper 并保持行为一致

Task K（已完成，第三轮）

继续拆分 ui/LUI/lui_function_properties.py::_draw_video_source_and_audio_controls（已完成）
验收:
- 单函数长度降到 <= 160 行（实际 4 行）
- 行为保持一致（本地视频/URL加载/音频联动）

Task L（已完成，第四轮）

继续拆分 ui/LUI/lui_function_properties.py::_draw_text_and_button_properties
验收:
- 单函数长度降到 <= 160 行（实际 14 行）
- 文本/按钮属性编辑行为保持一致

Task M（已完成，第四轮）

继续拆分 ui/LUI/lui_manager_editor.py::_set_parent_child_relationship
验收:
- 单函数长度降到 <= 180 行（实际 43 行）
- 父子关系编辑行为保持一致

Task N（推荐下一步，1-2 天）

拆分 ui/panels/editor_panels_top.py::draw_menu_bar
验收:
- 单函数长度降到 <= 170 行
- 菜单项顺序与行为保持一致

Task O（已完成，第四轮）

继续拆分 ui/LUI/lui_function_properties.py::_draw_layout_transform_properties
验收:
- 单函数长度降到 <= 160 行（实际 10 行）
- 布局与尺寸联动行为保持一致

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/panels/editor_panels_top.py::draw_menu_bar。

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）

loadScene 已完成两轮拆分（当前建议冻结并转入回归观察）。
main.__init__ 已完成第一轮拆分（建议转入回归观察）。
_update_drag 已完成第一轮拆分，建议转入回归观察。
_draw_component_properties 第一轮已完成，_draw_type_specific_properties 二轮与视频段三轮已完成。
_handle_resize_drag 第三轮细拆已完成，_draw_text_and_button_properties、_set_parent_child_relationship、_draw_layout_transform_properties 第四轮已完成。

5. 与现有文档关系

模块总索引: PROJECT_MODULE_INDEX.md
项目任务清单: PROJECT_TASK_CHECKLIST.md
历史分析: IMGUI_MODULE_ANALYSIS.md

如果按此路线继续，建议下一轮直接从 Task N 开始，优先落地 draw_menu_bar 的流程拆分并保持行为不变。

20 KiB Raw Blame History Unescape Escape