# 分镜图片 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`