# Changelog: 分镜列表对接后端 API

**日期**: 2026-02-09  
**类型**: 功能优化  
**影响范围**: ParseFlowDialog 分镜列表展示  

---

## 变更概述

将 `ParseFlowDialog` 中的分镜列表从本地 mock 数据切换为后端 API 数据源，实现真实数据展示。

---

## 变更详情

### 1. 数据源切换

**修改文件**: `client/src/components/features/storyboard/ParseFlowDialog.tsx`

**变更位置**: 第 1147-1181 行 `useEffect` 初始化逻辑

**改动内容**:
- ✅ 从后端 `storyboards` 数据同步到本地 `shots` 状态
- ✅ 使用已有的 `convertStoryboardsToShots` 转换函数
- ✅ 移除 mock 数据：删除自动创建空分镜的逻辑
- ✅ 后端无数据时显示空列表，引导用户手动添加

**核心改动**:

```typescript
// 原逻辑：自动创建空分镜（mock）
if (parsed.length === 0) {
  const newId = generateUUID();
  parsed.push({
    id: newId,
    title: '新分镜 1',
    content: '',
    duration: 3,
    // ... 其他字段
  });
}

// 新逻辑：不自动创建，显示空态
// 用户可通过"添加分镜"按钮手动创建
```

---

## 功能表现

### 打开弹窗时

| 场景 | 旧行为 | 新行为 |
|------|--------|--------|
| 后端有分镜 | 显示 mock 数据（1 个空分镜） | 显示后端真实分镜列表 |
| 后端无分镜 | 显示 mock 数据（1 个空分镜） | 显示空态 + "新建分镜"按钮 |

### 编辑流程

1. ✅ 打开弹窗 → 自动加载后端分镜列表
2. ✅ 编辑分镜 → 修改本地 `shots` 状态（流畅编辑）
3. ✅ 点击"应用到项目" → 保存到后端（批量提交）

---

## 技术细节

### API 调用链

```
ParseFlowDialog
  ↓ useStoryboards(projectId)
  ↓ storyboardApi.getByProjectId()
  ↓ GET /api/v1/storyboards?project_id={id}
  ↓ 返回 Storyboard[]
  ↓ convertStoryboardsToShots()
  ↓ 转换为 DraftShot[] (本地编辑格式)
  ↓ setShots() (更新列表状态)
```

### 数据转换逻辑

`convertStoryboardsToShots` 函数负责将后端数据结构转换为前端编辑格式：

```typescript
{
  id: item.id.toString(),
  title: item.title,
  duration: sb.duration ?? (item.endTime - item.startTime),
  shotNumber: shotMatch?.[1] ?? (index + 1).toString(),
  shotType: sb.angle || '',
  cameraMovement: sb.cameraMovement || '',
  description: item.description || '',
  characters: [...], // 从 resources 映射
  locations: [...],
  props: [...],
  // ...
}
```

---

## 依赖关系

### 相关 Hook

- `useStoryboards(projectId)`: 获取项目分镜列表
- `useResources(projectId)`: 获取资源库（用于名称映射）

### 相关组件

- `ParseFlowStoryboardListPanel`: 分镜列表展示面板
- `StoryboardEditForm`: 分镜编辑表单

---

## 测试要点

### 场景 1: 后端有分镜数据
1. 打开弹窗
2. 验证：分镜列表显示后端数据（标题、时长、描述等）
3. 验证：选中第一个分镜，右侧表单显示详情

### 场景 2: 后端无分镜数据
1. 打开弹窗
2. 验证：显示空态 UI（"暂无分镜"）
3. 验证：点击"新建分镜"按钮可添加

### 场景 3: 编辑并保存
1. 编辑分镜（修改标题、描述等）
2. 点击"应用到项目"
3. 验证：后端数据已更新
4. 重新打开弹窗，验证：显示最新数据

---

## 潜在影响

### 兼容性
✅ 向下兼容：保留现有编辑逻辑，仅改变数据来源

### 性能
✅ 无性能退化：
- 使用 React Query 缓存（5 分钟 staleTime）
- 转换逻辑在客户端执行（秒级完成）

### 用户体验
✅ 改进点：
- 真实数据展示，避免 mock 数据误导
- 空态引导更清晰（"新建分镜"按钮）

---

## 后续优化建议

1. **实时保存**: 考虑在字段修改时自动保存（需增加防抖）
2. **冲突处理**: 多用户同时编辑时的冲突检测
3. **离线支持**: 编辑缓存到本地存储，网络恢复后同步

---

## 相关文档

- [分镜 API 文档](../../server/guides/storyboard-api.md)
- [useStoryboards Hook](../../client/guides/api-hooks.md#usestoryboards)
- [ParseFlowDialog 组件文档](../../client/guides/parse-flow-dialog.md)