bim_engine/.sisyphus/drafts/framework-optimization.md

Draft: Framework/Architecture Optimization

Requirements (confirmed)

• User wants a project-wide review of the current framework/architecture.
• Goal: identify framework-level optimizations to reduce complexity and the need to "jump around" to make changes.
• Concern reported by others: the framework feels "too complex" (likely too many indirections/cross-calls).

User Preferences (confirmed)

• Focus areas: module layering + dependency injection/service locator complexity.
• Preferred output: a problem list (issues + evidence paths + impact), not a full refactor roadmap (for now).

Deliverable Format (confirmed)

• Provide: issue list + severity + evidence (paths/call chains). No redesign/implementation proposals in this pass.

Evaluation Focus (confirmed)

• User wants objective evaluation focused on maintenance cost (readability/changeability/testability).

Layering Constraint (confirmed)

• Components should be strict UI only: do not touch registry and do not emit global events.
• Components should also NOT directly subscribe/read global theme/locale services; managers should inject theme/locale or push updates.

Evaluation Criteria (confirmed)

• Evaluate complexity from: readability, changeability, testability, runtime performance, build efficiency.
• Risk tolerance: user is open to large refactors if justified.

Compatibility Preference (confirmed)

• User is OK with a major-version upgrade and breaking API changes if it yields a simpler SDK facade.

Multi-instance Requirement (confirmed)

• Must support multiple BimEngine instances on the same page, isolated per container.

Desired Public API UX (confirmed)

• Prefer single-entry, mostly-automatic initialization; internal modules can be lazy/optional.

Global vs Instance State (confirmed)

• Theme/locale should be global across all viewers on the same page (change once applies to all).

Event Model (confirmed)

• Events should be isolated per BimEngine instance (no implicit cross-instance broadcast).

Design Constraint (confirmed)

• Keep ManagerRegistry as a core design; critique should focus on boundary rules and misuse patterns rather than removing it.

Registry Model Decision (confirmed)

• User wants to keep ManagerRegistry as a global singleton (not per-engine instance).

Observations (from user)

• "要调来调去" suggests high coupling, too many layers, or hard-to-trace control flow.

Additional User Context (confirmed)

• User believes current design is intentionally decoupled; wants an objective, fair assessment of where the framework/architecture has problems.
• User is not sure which part is complex; expects reviewer to discover issues by reading the project.

User Instruction (confirmed)

• User requests reviewer-style assessment without asking many implementation-preference questions.

Output Artifact

• Audit report drafted at: .sisyphus/drafts/framework-audit-report.md.

Build/Distribution Context (confirmed)

• Built with npm.
• Output is an SDK/library consumed by third-party callers.

SDK Entry Point (evidence)

• Demo uses UMD global window.IflowEngine.BimEngine and instantiates via new Engine('app', { locale: 'zh-CN' }).
  • Evidence: demo/index.html:207-215, demo/viewer.html:151-160.
• Public surface in demo is manager-like properties: engine.toolbar, engine.dialog, engine.propertyPanel, and nested 3D engine access engine.engine.initialize() / engine.engine.loadModel().
  • Evidence: demo/index.html:228-307, demo/index.html:343-467, demo/index.html:469-478.

Primary Distribution Target (confirmed)

• Primary consumption: ESM import { BimEngine } from 'iflow-engine'.

Early Code Findings (evidence; subject to deeper review)

• BimEngine currently eagerly constructs many managers inside its constructor flow (this.init()), rather than requiring external initX() calls.
  • Evidence: src/bim-engine.ts:46-69, src/bim-engine.ts:95-142.
• There is a singleton-style registry/service-locator (ManagerRegistry.getInstance()), and BimEngine writes many manager references into it.
  • Evidence: src/bim-engine.ts:57-58, src/bim-engine.ts:101-136.
• This creates a potential mismatch with docs that describe “user calls initEngine()/initToolbar()/...” as a step-by-step initialization.
  • Evidence: README.md “快速开始/初始化各个管理器” section vs src/bim-engine.ts eager init.
• Build is Vite library mode, with inlineDynamicImports: true (single-file bundle), which can reduce ESM tree-shaking benefits and may increase load size.
  • Evidence: vite.config.ts:26-38, package.json:5-13.

Doc Findings (evidence)

• Architecture docs explicitly define ManagerRegistry as Singleton + Service Locator, and many call chains obtain it via ManagerRegistry.getInstance() even in leaf button configs.
  • Evidence: docs/架构设计.md:100-115, docs/API调用链.md:69-93.
• Call-chain doc shows deep 5-layer pipeline (Button -> DialogManager -> EngineManager -> Engine component -> base engine). This is understandable but can feel "too many hops" when changes span layers.
  • Evidence: docs/API调用链.md:714-748.
• Core docs show ManagerRegistry stores container/wrapper plus many manager instances, making it effectively a global mutable bag of state.
  • Evidence: docs/MODULES/核心模块.md:114-137.

Technical Decisions

• TBD

Research Findings

• Pending codebase exploration.

Scope Boundaries

• INCLUDE: architecture review, module boundaries, dependency direction, layering, wiring/DI, config/initialization flow, build/runtime structure.
• EXCLUDE: feature work unless explicitly requested; large refactor without a plan.

Open Questions

• What does "framework" refer to here (backend framework / engine core architecture / plugin system / build system)?
• What are the top pain points (debugging, onboarding, adding features, runtime performance, build speed)?
• What constraints exist (API stability, deadlines, must-keep patterns, target platforms)?