docs/v1.0/client/changelogs/2026-02-12-storyboard-images-api-integration.md

分镜图片 API 对接

概述

分镜预览中的图片展示与增删改功能完全由后端 API 驱动，移除本地 mock 数据。

变更内容

1. 新增 API 服务

• 文件：client/src/services/api/storyboard-resources.ts
• 接口：
  • getStoryboardImages(storyboardId) - GET 获取分镜所有图片
  • uploadStoryboardImage(storyboardId, file, name?, description?) - POST 上传自定义图片
  • updateStoryboardImage(imageId, payload) - PATCH 更新图片
  • activateStoryboardImage(imageId) - POST 设置激活图片
  • deleteStoryboardImage(imageId) - DELETE 删除图片

2. 新增 Hook

• 文件：client/src/hooks/api/useStoryboardImages.ts
• 集成 TanStack Query，提供 images、uploadImage、updateImage、activateImage、deleteImage 及加载状态

3. 数据流改造

• usePreviewData：分镜预览项由 storyboardImages API 数据映射为 StoryboardItem[]，移除硬编码 mock
• PreviewPanel：移除 customStoryboardItems 状态，完全由后端数据驱动

4. 交互逻辑

操作	实现
展示缩略图	GET /storyboard-resources/storyboards/{id}/images
新增自定义图片	POST upload，成功后 refetch
切换方案	选中非激活项时自动调用 activate API
更新方案	PATCH 更新 name/description
删除方案	DELETE，激活图片时提示「请先切换到其他方案再删除」

5. ID 设计

• 分镜图片项 id 直接使用后端 imageId（UUID），便于 PATCH/DELETE 调用
• 选中状态通过 editorContext.previewItemId 存储

涉及文件

• 新增：storyboard-resources.ts、useStoryboardImages.ts
• 修改：usePreviewData.ts、PreviewPanel.tsx、api/index.ts、hooks/api/index.ts