docs/v1.0/client/changelogs/2026-02-09-storyboard-backend-integration.md

Changelog: 分镜列表对接后端 API

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

---

变更概述

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

---

变更详情

1. 数据源切换

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

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

改动内容:

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

核心改动:

// 原逻辑：自动创建空分镜（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 函数负责将后端数据结构转换为前端编辑格式：

{
  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 文档
• useStoryboards Hook
• ParseFlowDialog 组件文档