# 拖拽吸附功能 - 潜在Bug分析报告

## 🔴 严重问题（可能导致间歇性失败）

### Bug #1: **竞态条件 - dragStartPosition 可能为 null**
**位置：** `AppModelDrag.ts:156-159`

```typescript
let hasMoved = false;
if (meshes && meshes.length > 0 && dragStartPosition) {
    const distance = Vector3.Distance(dragStartPosition, meshes[0].position);
    hasMoved = distance > 0.01;
}
```

**问题：**
- `dragStartPosition` 是闭包变量，在多次快速拖拽时可能在 `onDragEndObservable` 触发前被清空
- 如果用户**快速点击-拖动-松开**（<50ms），`dragStartPosition` 可能还未设置就被读取

**触发条件：** 快速拖拽，或高延迟场景下事件顺序错乱

**修复方案：**
```typescript
// 在 onDragStartObservable 中保存到 dragInfo
pointerDragBehavior.onDragStartObservable.add(() => {
    const meshes = this.mainApp.appModel?.modelDic?.Get(modelId);
    if (meshes && meshes.length > 0) {
        if (!dragInfo.startPosition) {
            dragInfo.startPosition = meshes[0].position.clone();
        }
    }
    // ...
});

// 在 onDragEndObservable 中使用持久化的位置
if (meshes && meshes.length > 0 && dragInfo.startPosition) {
    const distance = Vector3.Distance(dragInfo.startPosition, meshes[0].position);
    hasMoved = distance > 0.01;
    dragInfo.startPosition = null; // 清除
}
```

---

### Bug #2: **映射更新时机问题 - 可能丢失映射**
**位置：** `AppModelDrag.ts:165-174`

```typescript
if (hasMoved) {
    if (dragInfo.config.snapToZone && hasShownZones) {
        this.hideZonesForModel(modelId);
        this.snapModelToZone(modelId);  // ← 这里会 return，不更新映射
    } else {
        this.updateModelZoneMapping(modelId);
    }
}
```

**问题：**
- `snapModelToZone()` 内部有多个 `return` 语句（444、452、483行）
- 当返回原位置时，会 `return` 并**注释说"不更新映射，保持原映射"**
- 但如果 `zoneModelMap` 在此之前被意外清空（如替换模式交换），映射就丢失了

**触发条件：**
1. 拖拽到已占用区域
2. 配置为返回原位置
3. 但原映射已被其他操作修改

**修复方案：**
```typescript
// snapModelToZone 内部返回前，确保映射存在
if (originalZoneIndex !== -1) {
    const originalKey = `${wallName}[${originalZoneIndex}]`;
    // 强制恢复映射
    appDropZone['zoneModelMap']?.set(originalKey, modelId);
    console.log(`[拖拽吸附] 恢复映射: ${originalKey} -> ${modelId}`);
    return;
}
```

---

### Bug #3: **边界检测逻辑缺陷 - Y轴未检查**
**位置：** `AppModelDrag.ts:390-423`

```typescript
// 计算墙面的边界
let minX = Number.POSITIVE_INFINITY;
let maxX = Number.NEGATIVE_INFINITY;
let minZ = Number.POSITIVE_INFINITY;
let maxZ = Number.NEGATIVE_INFINITY;

wallZones.forEach(zone => {
    const halfWidth = zone.width / 2;
    
    if (Math.abs(zone.normal.x) > 0.5) {
        // 左右墙面
        minZ = Math.min(minZ, zone.center.z - halfWidth);
        maxZ = Math.max(maxZ, zone.center.z + halfWidth);
    } else if (Math.abs(zone.normal.z) > 0.5) {
        // 前后墙面
        minX = Math.min(minX, zone.center.x - halfWidth);
        maxX = Math.max(maxX, zone.center.x + halfWidth);
    }
});

// ❌ 问题：Y轴完全未检查！
const currentPos = rootMesh.position;
if (minX !== Number.POSITIVE_INFINITY && maxX !== Number.NEGATIVE_INFINITY) {
    if (currentPos.x < minX || currentPos.x > maxX) {
        isOutOfBounds = true;
    }
}
```

**问题：**
- 只检查 X 和 Z 轴，**Y轴完全不检查**
- 如果用户切换到 Y 轴拖拽，配件可以无限上下移动而不会触发"超出边界"
- 配件可能飞到天上或地下，但系统认为"在边界内"

**触发条件：**
1. 启用 Y 轴拖拽 (`axis: 'y'` 或 `'xyz'`)
2. 向上或向下拖拽
3. 边界检测失效

**修复方案：**
```typescript
// 添加 Y 轴边界检查
let minY = Number.POSITIVE_INFINITY;
let maxY = Number.NEGATIVE_INFINITY;

wallZones.forEach(zone => {
    const halfHeight = zone.height / 2;
    minY = Math.min(minY, zone.center.y - halfHeight);
    maxY = Math.max(maxY, zone.center.y + halfHeight);
    // ... 原有 X/Z 检查
});

// 检查 Y 轴
if (minY !== Number.POSITIVE_INFINITY && maxY !== Number.NEGATIVE_INFINITY) {
    if (currentPos.y < minY || currentPos.y > maxY) {
        isOutOfBounds = true;
    }
}
```

---

## 🟡 中等问题（可能导致不一致）

### Bug #4: **旋转角度计算不完整**
**位置：** `AppModelDrag.ts:439-441, 478-480, 504-506`

```typescript
const targetDirection = originalZone.normal.scale(-1);
const angle = Math.atan2(targetDirection.x, targetDirection.z);
rootMesh.rotation.y = angle;
```

**问题：**
- 只更新 Y 轴旋转，假设配件永远直立
- 如果配件初始有 X 或 Z 轴旋转（倾斜），吸附后会**丢失这些旋转**
- 对于可旋转的配件（如斜挂的装饰），会出现"吸附后变歪"的问题

**触发条件：** 配件有非零的 rotation.x 或 rotation.z

**修复方案：**
```typescript
// 保存并恢复其他轴的旋转
const originalRotationX = rootMesh.rotation.x;
const originalRotationZ = rootMesh.rotation.z;

const targetDirection = originalZone.normal.scale(-1);
const angle = Math.atan2(targetDirection.x, targetDirection.z);
rootMesh.rotation.y = angle;

// 恢复其他轴
rootMesh.rotation.x = originalRotationX;
rootMesh.rotation.z = originalRotationZ;
```

---

### Bug #5: **替换模式下的映射覆盖冲突**
**位置：** `AppModelDrag.ts:612-640 + AppDropZone.ts:229-234`

**问题：**
`AppModelDrag.updateModelZoneMapping()` 和 `AppDropZone.onModelPlaced()` 都会操作 `zoneModelMap`，可能产生竞态：

**时序问题：**
```
1. 用户拖拽模型A到模型B所在位置
2. AppModelDrag 删除 oldKey[A]
3. AppModelDrag 检测到 newKey 已有模型B
4. AppModelDrag 设置 swapKey[B] = B （交换）
5. AppModelDrag 设置 newKey = A
6. ❌ 此时如果 AppDropZone.onModelPlaced() 也触发...
7. AppDropZone 检测到 newKey 已有A
8. AppDropZone 删除模型A（认为是旧模型！）
9. 结果：模型A和B都消失了
```

**触发条件：**
- 替换模式 + 快速连续拖拽
- 或者某个事件触发了 `onModelPlaced()`

**修复方案：**
```typescript
// 在 updateModelZoneMapping 中添加锁
private isUpdatingMapping = false;

private updateModelZoneMapping(modelId: string): void {
    if (this.isUpdatingMapping) {
        console.warn(`[映射更新] 正在更新中，跳过 ${modelId}`);
        return;
    }
    
    this.isUpdatingMapping = true;
    try {
        // ... 原有逻辑
    } finally {
        this.isUpdatingMapping = false;
    }
}
```

---

### Bug #6: **最近区域查找可能不准确**
**位置：** `AppModelDrag.ts:367-377, 559-568`

```typescript
wallZones.forEach((zone, index) => {
    const distance = rootMesh.position.subtract(zone.center).length();
    if (distance < minDistance) {
        minDistance = distance;
        closestZoneIndex = index;
    }
});
```

**问题：**
- 使用欧几里得距离（3D空间直线距离）
- 但配件应该吸附到**墙面上的投影点**，而不是空间距离
- 如果配件被拖到离墙面很远的地方，可能吸附到错误的区域

**示例：**
```
墙面：Z=0
区域0: center=(0, 1, 0)
区域1: center=(5, 1, 0)

配件位置: (2.5, 10, 0)  ← 离墙面很远，但在正中间

空间距离：
- 到区域0: √((2.5-0)² + (10-1)² + 0²) = √87.25 ≈ 9.34
- 到区域1: √((2.5-5)² + (10-1)² + 0²) = √87.25 ≈ 9.34

结果：可能选中任意一个（取决于遍历顺序）
```

**正确做法：** 应该先投影到墙面，再计算2D距离

**修复方案：**
```typescript
wallZones.forEach((zone, index) => {
    // 计算到墙面的投影点
    const toModel = rootMesh.position.subtract(zone.center);
    const distanceToPlane = Vector3.Dot(toModel, zone.normal);
    const projectedPoint = rootMesh.position.subtract(zone.normal.scale(distanceToPlane));
    
    // 使用投影点到区域中心的距离
    const distance = projectedPoint.subtract(zone.center).length();
    
    if (distance < minDistance) {
        minDistance = distance;
        closestZoneIndex = index;
    }
});
```

---

## 🟢 轻微问题（边缘情况）

### Bug #7: **闭包变量状态泄漏**
**位置：** `AppModelDrag.ts:118-119, 176-178`

```typescript
let dragStartPosition: Vector3 | null = null;
let hasShownZones = false;

// onDragEndObservable 结束时清除
dragStartPosition = null;
hasShownZones = false;
```

**问题：**
- 如果 `onDragEndObservable` 因异常未触发，这些变量永远不会清除
- 下次拖拽会使用**上次的脏数据**

**修复方案：**
```typescript
// 在 onDragStartObservable 开始时强制重置
pointerDragBehavior.onDragStartObservable.add(() => {
    // 强制清除旧状态（防止异常导致未清除）
    dragStartPosition = null;
    hasShownZones = false;
    
    // 然后记录新状态
    const meshes = this.mainApp.appModel?.modelDic?.Get(modelId);
    if (meshes && meshes.length > 0) {
        dragStartPosition = meshes[0].position.clone();
    }
    // ...
});
```

---

## 📋 修复优先级建议

### P0 - 立即修复
1. **Bug #1** - 竞态条件（可能导致吸附完全失效）
2. **Bug #2** - 映射丢失（配件消失）
3. **Bug #5** - 替换冲突（配件重复删除）

### P1 - 本周修复
4. **Bug #3** - Y轴边界检测（安全问题）
5. **Bug #6** - 吸附不准确（用户体验）

### P2 - 下周修复
6. **Bug #4** - 旋转丢失（视觉问题）
7. **Bug #7** - 状态泄漏（稳定性）

---

## 🧪 测试场景（复现间歇性Bug）

### 场景1：快速连续拖拽
```javascript
// 模拟用户快速拖拽
for (let i = 0; i < 10; i++) {
    setTimeout(() => {
        // 快速拖动配件A
        dragModel('accessory_A', randomPosition());
    }, i * 100); // 每100ms一次
}
```

### 场景2：替换模式压力测试
```javascript
// 两个配件互相替换
setInterval(() => {
    dragModel('accessory_A', positionB);
    setTimeout(() => {
        dragModel('accessory_B', positionA);
    }, 50);
}, 500);
```

### 场景3：边界外拖拽
```javascript
// 拖到墙外
dragModel('accessory_A', { x: 1000, y: 0, z: 0 });
// 预期：返回原位置
// 实际：可能映射丢失
```

### 场景4：Y轴拖拽
```javascript
// 启用Y轴拖拽
kernel.drag.configure('accessory_A', { 
    enable: true, 
    axis: 'xyz',
    snapToZone: true 
});
// 向上拖100单位
dragModel('accessory_A', { x: 0, y: 100, z: 0 });
// 预期：触发边界检测
// 实际：边界检测失效
```

---

## 💡 总结

拖拽吸附功能的间歇性问题主要来自：
1. **异步状态管理不当**（Bug #1, #7）
2. **映射更新时序冲突**（Bug #2, #5）
3. **边界检测不完整**（Bug #3）
4. **算法不够精确**（Bug #6）

建议优先修复 Bug #1、#2、#5，这些会导致明显的功能失效。