jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3 Commits
1 Branch
0 Tags
2.6 MiB
 
Branch: main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
docs/v1.0/client/changelogs/2026-02-01-storyboard-mock-...

5.4 KiB
Raw Permalink Blame History

Storyboard Mock 数据 API 字段对齐

日期：2026-02-01
类型：数据规范化
影响范围：Mock 数据

变更概述

对齐 client/src/mocks/storyboards.ts Mock 数据与后端 API 文档字段规范，确保前端开发时使用的 Mock 数据结构与真实 API 响应一致。

主要变更

1. 字段命名规范化

主键和外键字段

  • ✅ 保持 id (前端 camelCase) ← API storyboard_id (snake_case)
  • ✅ 保持 projectId ← API project_id

新增必填字段

  • ✅ shotNumber: 镜号（如 "001", "002"），自动生成
  • ✅ shotSize: 景别（SMALLINT 1-8）
  • ✅ cameraMovement: 运镜（SMALLINT 1-9）
  • ✅ estimatedDuration: 预估时长（秒）
  • ✅ actualDuration: 实际时长（秒）

字段类型调整

  • ✅ dialogue: 从数组改为单个字符串（API 规范）
  • ✅ cameraMovement: 从字符串改为枚举数字（1-9）
  • ✅ resources: 结构从 { resourceId, displayOrder } 改为 { id, name }

2. 枚举类型定义

景别枚举（ShotSize）

export enum ShotSize {
  EXTREME_WIDE_SHOT = 1,  // 大远景
  WIDE_SHOT = 2,          // 远景
  FULL_SHOT = 3,          // 全景
  MEDIUM_SHOT = 4,        // 中景
  MEDIUM_CLOSE_UP = 5,    // 中近景
  CLOSE_UP = 6,           // 特写
  EXTREME_CLOSE_UP = 7,   // 大特写
  OVER_SHOULDER = 8,      // 过肩镜头
}

运镜枚举（CameraMovement）

export enum CameraMovement {
  STATIC = 1,     // 固定
  PAN = 2,        // 摇镜
  TILT = 3,       // 俯仰
  DOLLY = 4,      // 推拉
  ZOOM = 5,       // 变焦
  TRACKING = 6,   // 跟踪
  ARC = 7,        // 环绕
  CRANE = 8,      // 升降
  HANDHELD = 9,   // 手持
}

3. 资源关联结构

API 格式

{
  "resources": {
    "characters": [{ "id": "uuid", "name": "角色名" }],
    "scenes": [{ "id": "uuid", "name": "场景名" }],
    "props": [{ "id": "uuid", "name": "道具名" }]
  }
}

Mock 格式（前端使用 locations）

{
  resources: {
    characters: [{ id: "uuid", name: "角色名" }],
    locations: [{ id: "uuid", name: "场景名" }], // 对应 API 的 scenes
    props: [{ id: "uuid", name: "道具名" }]
  }
}

4. UI 扩展字段

以下字段仅用于前端 UI，不在 API 中：

  • dialogues: 对白数组（前端扩展）
  • prompt: AI 生成提示词
  • status: 生成状态
  • angle: 拍摄角度
  • isFinalized: 是否已定稿
  • imageUrl: 图片 URL
  • videoUrl: 视频 URL
  • order: 兼容字段（等同于 orderIndex）
  • duration: 兼容字段（计算值）

文件变更

修改的文件

  • client/src/mocks/storyboards.ts - 更新 Mock 数据结构

新增的文件

  • client/src/mocks/storyboards-api-mapping.md - 字段映射文档
  • client/src/mocks/generate-storyboards.py - 数据生成脚本
  • client/src/mocks/storyboards-generated.txt - 生成的示例代码

API 文档参考

数据示例

更新前（旧格式）

{
  id: '018e1234-5678-7abc-8def-300000000001',
  projectId: '018e1234-5678-7abc-8def-100000000001',
  title: '五行山全景',
  description: '...',
  orderIndex: 1,
  startTime: 0,
  endTime: 4,
  cameraMovement: 'crane_down', // ❌ 字符串
  resources: {
    locations: [{ resourceId: 'uuid', displayOrder: 0 }] // ❌ 旧结构
  }
}

更新后（新格式）

{
  id: '018e1234-5678-7abc-8def-300000000001',
  projectId: '018e1234-5678-7abc-8def-100000000001',
  shotNumber: '001', // ✅ 新增
  title: '五行山全景',
  description: '...',
  dialogue: undefined, // ✅ 单个字符串
  shotSize: ShotSize.EXTREME_WIDE_SHOT, // ✅ 枚举数字
  cameraMovement: CameraMovement.CRANE, // ✅ 枚举数字
  estimatedDuration: 4.0, // ✅ 新增
  actualDuration: 4.0, // ✅ 新增
  orderIndex: 1,
  startTime: 0,
  endTime: 4,
  metadata: { // ✅ 扩展字段
    lighting: '自然光',
    weather: '阴天',
    time_of_day: '傍晚'
  },
  resources: {
    locations: [{ id: 'uuid', name: '五行山' }] // ✅ 新结构
  }
}

后续工作

类型定义更新

  • 更新 client/src/types/storyboard.ts 类型定义
  • 添加 ShotSize 和 CameraMovement 枚举导出
  • 更新 StoryboardWithUI 接口

组件适配

  • 更新使用分镜数据的组件（PreviewPanel, Timeline 等）
  • 适配新的 resources 结构
  • 处理 dialogue 字符串与 dialogues 数组的转换

API 集成

  • 创建 API 响应转换函数（snake_case → camelCase）
  • 实现枚举值的双向转换（数字 ↔ 字符串）
  • 添加 API 响应类型定义

测试建议

  1. 类型检查：运行 npm run type-check 确保类型正确
  2. 组件测试：测试使用分镜数据的所有组件
  3. 数据转换：测试 API 响应转换逻辑
  4. 枚举映射：验证景别和运镜枚举的正确性

参考资料