# 分镜排序系统重构方案

## 概述

全面重构分镜排序系统，解决数据结构不一致、ID类型混乱、拖拽清空和插入位置错误等问题。

## 核心问题分析

### 1. 数据结构不一致

**问题**：代码中同时使用 `order` 和 `orderIndex` 字段
**影响**：导致数据更新不同步，缓存逻辑错误
**解决**：统一使用 `orderIndex` 字段

### 2. ID类型混乱

**问题**：ID在string和number之间转换不一致
**影响**：拖拽时找不到对应分镜，导致清空
**解决**：统一使用number类型ID

### 3. 插入位置计算错误

**问题**：基于数组索引而非实际orderIndex计算
**影响**：插入位置与用户预期不符
**解决**：基于分镜的orderIndex计算插入位置

## 技术实现

### API层面修改

#### 1. 统一字段引用

```typescript
// 修复前：混用order和orderIndex
s.order = index + 1; // ❌
s.orderIndex = index + 1; // ✅

// 修复前：ID类型不一致
storyboards.find((s) => s.id === id); // ❌ string查找
storyboards.find((s) => s.id === parseInt(id)); // ✅ number查找
```

#### 2. 重写排序逻辑

```typescript
// create方法：插入时重新排序
if (targetOrderIndex !== undefined) {
  projectStoryboards
    .filter((s) => s.orderIndex >= targetOrderIndex)
    .forEach((s) => {
      s.orderIndex += 1;
      s.updatedAt = new Date().toISOString();
    });
}

// reorder方法：拖拽时重新分配orderIndex
orderedIds.forEach((id, index) => {
  const storyboard = storyboards.find((s) => s.id === parseInt(id));
  if (storyboard && storyboard.projectId === numericProjectId) {
    storyboard.orderIndex = index + 1;
    storyboard.updatedAt = new Date().toISOString();
  }
});
```

### 前端层面修改

#### 1. 修复缓存逻辑

```typescript
// 修复前：使用order字段
return { ...storyboard, order: index + 1 }; // ❌

// 修复后：使用orderIndex字段
return { ...storyboard, orderIndex: index + 1 }; // ✅
```

#### 2. 修正插入逻辑

```typescript
// 修复前：基于数组索引
onClick={() => handleInsertStoryboard(index + 2)}  // ❌

// 修复后：基于实际orderIndex
onClick={() => handleInsertStoryboard(storyboard.orderIndex + 1)}  // ✅
```

## 数据流程图

```
用户操作 → UI组件 → API调用 → 数据更新 → 缓存更新 → UI重渲染

插入分镜：
1. 用户点击插入按钮
2. 传递 storyboard.orderIndex + 1
3. API在指定位置插入，后续分镜orderIndex+1
4. 缓存更新，UI重新渲染

拖拽排序：
1. 用户拖拽分镜
2. 生成新的orderedIds数组
3. API重新分配所有分镜的orderIndex
4. 缓存更新，UI重新渲染
```

## 测试用例

### 插入功能测试

1. **第一个位置插入**：点击第一个插入按钮，新分镜应出现在最前面
2. **中间位置插入**：点击分镜2后的插入按钮，新分镜应出现在分镜2和分镜3之间
3. **连续插入**：多次插入，每次位置都应准确

### 拖拽功能测试

1. **简单拖拽**：将分镜1拖到分镜3后面，顺序应变为：分镜2, 分镜3, 分镜1
2. **复杂拖拽**：多次拖拽，分镜不应消失或重复
3. **拖拽后插入**：拖拽后再插入，位置应准确

## 性能优化

### 1. 批量更新

- 插入和拖拽操作一次性更新所有受影响的分镜
- 避免多次数据库操作

### 2. 缓存策略

- 使用乐观更新，立即反映UI变化
- 错误时回滚到之前状态

### 3. 内存管理

- 及时清理无用的缓存数据
- 避免内存泄漏

## 向后兼容性

### 数据迁移

- 现有数据结构保持不变
- 新字段向后兼容
- 渐进式升级策略

### API兼容

- 保持现有API接口不变
- 内部实现优化
- 不影响其他模块

## 监控和日志

### 关键指标

- 插入操作成功率
- 拖拽操作成功率
- 数据一致性检查

### 错误处理

- 操作失败时的回滚机制
- 详细的错误日志记录
- 用户友好的错误提示

## 总结

本次重构彻底解决了分镜排序系统的核心问题：

1. ✅ 统一数据结构，消除字段混用
2. ✅ 统一ID类型，确保查找准确
3. ✅ 修正插入逻辑，位置计算准确
4. ✅ 修复拖拽功能，不再清空分镜
5. ✅ 提升系统稳定性和可维护性

重构后的系统具有更好的数据一致性、更准确的功能表现和更强的扩展性。