docs/v1.0/.archive/client/storyboard-sorting.md

分镜排序系统重构计划

背景

分镜排序系统存在多个严重问题：

1. 数据结构不一致（order vs orderIndex）
2. ID类型混乱（string vs number）
3. 拖拽排序导致分镜清空
4. 插入位置计算错误

重构目标

• 统一数据结构和类型定义
• 修复拖拽排序功能
• 确保插入位置准确
• 提升系统稳定性

执行步骤

1. API层面重构

• 统一使用 orderIndex 字段
• 统一ID类型为number
• 修复duplicate方法字段引用
• 确保reorder方法正确处理ID类型

2. 前端缓存修复

• 修复reorderStoryboards hook中的字段引用
• 统一缓存更新逻辑使用orderIndex

3. UI层逻辑修复

• 重写插入位置计算逻辑
• 修正插入按钮调用参数
• 确保基于实际orderIndex计算插入位置

4. 核心原则

• orderIndex始终连续：1, 2, 3, 4...
• 任何操作后都重新计算orderIndex
• ID类型保持一致性（number）
• 插入位置基于实际orderIndex而非数组索引

预期结果

• ✅ 插入分镜位置完全准确
• ✅ 拖拽排序正常工作
• ✅ 数据结构完全一致
• ✅ 系统长期稳定

技术细节

插入逻辑

// 用户点击分镜后的插入按钮
onClick={() => handleInsertStoryboard(storyboard.orderIndex + 1)}

// 插入到指定orderIndex，后续分镜自动+1
const targetOrderIndex = data.orderIndex;
projectStoryboards
  .filter((s) => s.orderIndex >= targetOrderIndex)
  .forEach((s) => {
    s.orderIndex += 1;
  });

拖拽逻辑

// 基于新顺序重新分配orderIndex
orderedIds.forEach((id, index) => {
  const storyboard = storyboards.find((s) => s.id === parseInt(id));
  if (storyboard) {
    storyboard.orderIndex = index + 1;
  }
});

风险评估

• 低风险：主要是字段名和类型统一
• 向后兼容：不影响现有数据结构
• 测试覆盖：需要测试插入和拖拽功能

执行时间

2026-01-12