# zhengte.babylonjs-sdk 代码优化方案

## 优先级分级

### P0 - 紧急修复（立即）

1. **删除重复文件**
   - [ ] 删除 `src/babylonjs/AppModel copy.ts`
   - [ ] 确认所有引用都指向 `AppModel.ts`

2. **修复 applyMaterial 硬编码 Bug**
   ```typescript
   // GameManager.ts:824-825
   // 错误：这两行覆盖了用户传入的参数
   material.roughness = 0.8;  // ❌ 删除
   material.metallic = 0;     // ❌ 删除
   ```

3. **统一 offsetDistance**
   - [x] AppModelDrag.ts 第435行：`-0.05` → `0`
   - [x] AppModelDrag.ts 第474行：`-0.05` → `0`
   - [x] AppModelDrag.ts 第627行：`-0.05` → `0`

---

### P1 - 高优先级（本周内）

#### 1.1 代码清理
- [ ] 移除所有 `console.log`，保留 `console.warn/error`
- [ ] 统一使用 Logger 工具类
- [ ] 清理未使用的导入

#### 1.2 类型安全
```typescript
// 创建 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 错误处理统一
```typescript
// 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 统一数据结构命名
```typescript
// 统一使用 Map（性能更好，API 更清晰）
private oldTextureDic → private textureCache: Map<string, any>
private materialDic   → private materialMap: Map<string, PBRMaterial>
private modelDragMap  → 保持（已经是 Map）
```

#### 2.3 配置中心化
```typescript
// 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 事件系统解耦
```typescript
// 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 单元测试
```typescript
// 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% |