# 分镜时长拉伸功能修复

**日期**: 2026-02-08
**类型**: Bug 修复
**影响范围**: 分镜看板时长调整功能

## 问题描述

分镜看板中的拉伸功能（拖拽调整时长和直接输入时长）不工作，用户无法通过拖拽或输入来调整分镜时长。

## 根本原因

1. **数据不一致**：前端类型定义缺少 `actualDuration` 和 `estimatedDuration` 字段
2. **更新逻辑缺失**：拖拽调整时长时，只更新了 `endTime`，没有同步更新 `actualDuration` 字段
3. **后端依赖**：后端数据库模型中有 `actual_duration` 字段，但前端没有正确传递

## 修复方案

采用**方案 1：前端计算 actualDuration**

### 修改内容

#### 1. 更新类型定义

**文件**: `client/src/types/storyboard.ts`

```typescript
// 添加时长字段到 Storyboard 接口
export interface Storyboard {
  // ... 其他字段
  /** 预估时长（秒） */
  estimatedDuration?: number;
  /** 实际时长（秒） */
  actualDuration?: number;
  // ...
}

// 更新 DTO
export interface UpdateStoryboardDto {
  // ... 其他字段
  estimatedDuration?: number;
  actualDuration?: number;
  // ...
}
```

#### 2. 修改拖拽结束逻辑

**文件**: `client/src/hooks/useStoryboardBoardLogic.ts`

在 `handleDragEnd` 函数中添加时长变化检测和 `actualDuration` 更新：

```typescript
// 检查是否有本地状态变化（时长调整）
const localState = localItems[id];
const hasTimeChange = localState && (
  localState.startTime !== foundItem.startTime ||
  localState.endTime !== foundItem.endTime
);

// 如果有时长变化，更新 actualDuration
if (hasTimeChange && localState) {
  const newDuration = localState.endTime - localState.startTime;
  updateStoryboard({
    id: id,
    data: {
      startTime: localState.startTime,
      endTime: localState.endTime,
      actualDuration: newDuration,
    },
  });
}
```

## 功能验证

### 测试场景

1. **拖拽调整时长**
   - 拖拽分镜块右边界增加时长
   - 拖拽分镜块左边界减少时长
   - 验证时长显示正确更新
   - 验证后端 `actual_duration` 字段正确保存

2. **直接输入时长**
   - 点击分镜块上的时长显示
   - 在弹出的输入框中输入新时长（如 5.0 秒）
   - 点击确认按钮
   - 验证分镜块宽度正确调整
   - 验证后端数据正确保存

3. **边界情况**
   - 最小时长限制（0.5 秒）
   - 拖拽到时间轴边界
   - 快速连续调整

## 技术细节

### 数据流

```
用户操作（拖拽/输入）
  ↓
handleResizeRight/handleResizeLeft
  ↓
更新 localItems（实时预览）
  ↓
handleDragEnd（拖拽结束）
  ↓
检测时长变化
  ↓
计算 actualDuration = endTime - startTime
  ↓
调用 updateStoryboard API
  ↓
后端更新 actual_duration 字段
```

### API 调用

```typescript
updateStoryboard({
  id: storyboardId,
  data: {
    startTime: number,
    endTime: number,
    actualDuration: number, // 新增
  },
});
```

## 影响范围

- ✅ 分镜轨道时长调整
- ✅ 直接输入时长功能
- ✅ 拖拽调整时长功能
- ⚠️ 不影响其他轨道（资源、对白、音效等）

## 后续优化建议

1. **性能优化**：批量更新多个分镜时长时，考虑合并 API 请求
2. **用户体验**：添加时长调整的撤销/重做功能
3. **数据一致性**：定期同步 `actualDuration` 和 `endTime - startTime` 的一致性

## 相关文件

- `client/src/types/storyboard.ts`
- `client/src/hooks/useStoryboardBoardLogic.ts`
- `client/src/components/features/storyboard-board/StoryboardBoardItem.tsx`
- `server/app/models/storyboard.py`
- `server/app/schemas/storyboard.py`