zhengte.babylonjs-sdk/REFACTOR_PLAN.md

zhengte.babylonjs-sdk 代码优化方案

优先级分级

P0 - 紧急修复（立即）

1. 删除重复文件

   • 删除 src/babylonjs/AppModel copy.ts
   • 确认所有引用都指向 AppModel.ts

2. 修复 applyMaterial 硬编码 Bug

   // GameManager.ts:824-825
   // 错误：这两行覆盖了用户传入的参数
   material.roughness = 0.8;  // ❌ 删除
   material.metallic = 0;     // ❌ 删除
   

3. 统一 offsetDistance

   • AppModelDrag.ts 第435行：-0.05 → 0
   • AppModelDrag.ts 第474行：-0.05 → 0
   • AppModelDrag.ts 第627行：-0.05 → 0

---

P1 - 高优先级（本周内）

1.1 代码清理

• 移除所有 console.log，保留 console.warn/error
• 统一使用 Logger 工具类
• 清理未使用的导入

1.2 类型安全

// 创建 src/types/core.ts
export interface IMainApp {
  appScene: AppScene;
  appModel: AppModel;
  appCamera: AppCamera;
  gameManager: GameManager;
  appLight: AppLight;
  appModelDrag?: AppModelDrag;
  appDropZone?: AppDropZone;
  // ...
}

// 替换所有 any
constructor(mainApp: any) → constructor(mainApp: IMainApp)

1.3 错误处理统一

// src/utils/ErrorHandler.ts
export class AppError extends Error {
  constructor(
    message: string, 
    public code: string,
    public context?: any
  ) {
    super(message);
  }
}

export function handleError(error: Error | AppError): void {
  if (error instanceof AppError) {
    console.error(`[${error.code}] ${error.message}`, error.context);
  } else {
    console.error('Unexpected error:', error);
  }
  // 可以上报到监控系统
}

---

P2 - 中优先级（本月内）

2.1 拆分 GameManager

src/managers/
  ├── MaterialManager.ts      // 材质管理（200行）
  ├── TextureManager.ts       // 纹理加载（150行）
  ├── RollerDoorManager.ts    // 卷帘门动画（100行）
  ├── ClippingManager.ts      // Y轴剖切（80行）
  └── GameManager.ts          // 主协调器（<200行）

迁移步骤：

1. 创建 MaterialManager，迁移材质相关方法
2. GameManager 持有 MaterialManager 实例
3. 更新 Adapter 调用路径
4. 逐步迁移其他功能

2.2 统一数据结构命名

// 统一使用 Map（性能更好，API 更清晰）
private oldTextureDic → private textureCache: Map<string, any>
private materialDic   → private materialMap: Map<string, PBRMaterial>
private modelDragMap  → 保持（已经是 Map）

2.3 配置中心化

// src/config/constants.ts
export const PLACEMENT_CONFIG = {
  WALL_OFFSET: 0,           // 墙面偏移距离
  DRAG_THRESHOLD: 0.01,     // 拖拽阈值
  SNAP_ENABLED: true,       // 默认启用吸附
} as const;

// 使用
import { PLACEMENT_CONFIG } from '@/config/constants';
const offsetDistance = PLACEMENT_CONFIG.WALL_OFFSET;

---

P3 - 低优先级（长期优化）

3.1 事件系统解耦

// src/event/DomainEvents.ts
export enum DomainEvent {
  MODEL_LOADED = 'model:loaded',
  MATERIAL_UPDATED = 'material:updated',
  ZONE_OCCUPIED = 'zone:occupied',
}

// 使用
EventBus.emit(DomainEvent.MATERIAL_UPDATED, { materialId, properties });

// 监听
EventBus.on(DomainEvent.MATERIAL_UPDATED, (data) => {
  this.updateDictionaries();
});

3.2 文档完善

• 为所有 public 方法添加 JSDoc
• 说明参数类型和用途
• 添加使用示例

3.3 单元测试

// tests/managers/MaterialManager.test.ts
describe('MaterialManager', () => {
  it('should apply material properties correctly', () => {
    const manager = new MaterialManager(mockApp);
    manager.applyMaterial({
      target: 'test_material',
      roughness: 0.5,
    });
    expect(material.roughness).toBe(0.5);
  });
});

---

实施建议

渐进式重构策略

1. 先修复 Bug（P0）
2. 再提升质量（P1）
3. 最后优化架构（P2/P3）

风险控制

• ✅ 每次修改后运行完整测试
• ✅ 使用 Git 分支隔离重构工作
• ✅ 保持功能完全一致
• ✅ 逐模块重构，避免大爆炸式改动

验收标准

• 所有现有功能正常工作
• 无 TypeScript 类型错误
• 无 ESLint 警告
• 代码审查通过
• 性能无明显下降

---

预期收益

指标	当前	优化后	提升
代码行数	~5000行	~4500行	-10%
最大文件行数	836行	<300行	-64%
类型覆盖率	~40%	>90%	+125%
可维护性指数	C级	A级	+2级
Bug 数量	已知3个	0个	-100%