# 分镜资源总览功能

**日期**: 2026-02-01  
**类型**: Feature  
**影响范围**: PreviewPanel, StoryboardResourcesPreview

## 变更内容

### Bug 修复

**问题**: 点击分镜轨道块时，PreviewPanel 错误地显示资源总览而非分镜预览

**原因**: 判断条件只检查了 `selectedStoryboardId && !selectedResourceId`，没有区分点击来源（分镜轨道 vs 资源轨道）

**解决方案**: 添加 `resourcesPanelOpen` 状态检查，只有当资源面板打开时才显示资源总览

**修改逻辑**:
```typescript
// 修改前：
if (selectedStoryboardId && !selectedResourceId && currentStoryboard) {
  return <StoryboardResourcesPreview />;
}

// 修改后：
if (selectedStoryboardId && !selectedResourceId && resourcesPanelOpen && currentStoryboard) {
  return <StoryboardResourcesPreview />;
}
```

### 新增功能

1. **分镜资源总览组件** (`StoryboardResourcesPreview`)
   - 展示选中分镜关联的所有资源（角色、场景、道具、实拍）
   - 支持点击资源卡片切换到该资源的详细预览
   - 支持通过添加按钮关联新资源到分镜

2. **PreviewPanel 交互优化**
   - 点击分镜看板资源轨道块时，显示该分镜的资源总览
   - 点击资源总览中的资源卡片，切换到资源详细预览
   - 点击添加按钮，打开资源选择器关联资源

### UI 设计

#### 资源总览布局

```
┌─────────────────────────────────────────────────────────────┐
│  👤 角色 (3)                                        [+添加]  │
│  ┌──────┐  ┌──────┐  ┌──────┐                               │
│  │ 头像 │  │ 头像 │  │ 头像 │                               │
│  │ 3:4  │  │ 3:4  │  │ 3:4  │                               │
│  └──────┘  └──────┘  └──────┘                               │
│   角色名     角色名     角色名                                │
│   标签       标签       标签                                  │
└─────────────────────────────────────────────────────────────┘
```

#### 资源卡片设计

- **角色资源**: 3:4 比例缩略图 (48x64)
- **场景资源**: 16:9 比例缩略图 (64x36)
- **道具资源**: 1:1 比例缩略图 (48x48)
- **实拍资源**: 16:9 比例缩略图 (64x36)

#### 视觉规范

| 元素 | 规范 |
|------|------|
| 背景 | `bg-bg-element` |
| 行背景 | `bg-bg-page/30` (hover: `bg-bg-page/50`) |
| 卡片背景 | `bg-fill-lighter` (hover: `bg-fill-default`) |
| 边框 | `border-border-light` |
| 选中状态 | `border-primary ring-2 ring-primary/20` |
| 文字颜色 | 主要: `text-text-primary`, 次要: `text-text-tertiary` |

#### 交互设计

| 交互 | 行为 |
|------|------|
| hover 资源卡片 | 边框高亮 + 阴影 + cursor-pointer |
| 点击资源卡片 | 调用 `selectResource(resourceId)` 切换预览 |
| hover 添加按钮 | 背景变亮 |
| 点击添加按钮 | 打开 `ResourcePicker` 弹窗 |
| 资源被选中 | 边框变为主色 `border-primary` |

### 状态流转

```
用户操作                          → PreviewPanel 显示
─────────────────────────────────────────────────────────
点击分镜轨道块                    → 分镜多方案预览 ✓
点击资源轨道块                    → 该分镜资源总览 ✓
点击资源总览中的具体资源          → 该资源详细预览 ✓
点击资源库中的资源                → 该资源详细预览 ✓
```

**关键判断逻辑**:
- `resourcesPanelOpen = false` → 显示分镜预览（点击分镜轨道）
- `resourcesPanelOpen = true` → 显示资源总览（点击资源轨道）

## 技术实现

### 新增文件

1. `/client/src/components/features/preview/StoryboardResourcesPreview.tsx`
   - 资源总览组件
   - 资源卡片子组件
   - 分类展示逻辑

### 修改文件

1. `/client/src/components/features/preview/PreviewPanel.tsx`
   - 添加资源总览模式渲染逻辑
   - 实现 `handleAddResource` 处理资源添加
   - 使用 `useUpdateStoryboard` 更新分镜资源

### API 调用

- **获取项目资源**: `useResources(projectId)`
- **更新分镜资源**: `useUpdateStoryboard()`
- **资源结构**: `StoryboardResources` (characters, locations, props, footages)

### 性能优化

- 使用 `memo` 包装组件，减少重渲染
- 使用 `useMemo` 缓存分组资源计算
- 使用 `useCallback` 优化事件处理器

## 使用说明

### 查看分镜资源

1. 在分镜看板中点击任意资源轨道块
2. PreviewPanel 自动切换到资源总览模式
3. 查看该分镜关联的所有资源

### 添加资源到分镜

1. 在资源总览中点击对应类型的"添加"按钮
2. 从资源选择器中选择资源
3. 资源自动关联到分镜并更新显示

### 预览资源详情

1. 在资源总览中点击任意资源卡片
2. PreviewPanel 切换到该资源的详细预览
3. 支持多视图切换（角色三视图等）

## 依赖说明

- **UI 组件**: ResourcePicker, EmptyState
- **图标**: Lucide React (User, MapPin, Package, Camera)
- **状态管理**: editorStore (selectResource)
- **API Hooks**: useResources, useUpdateStoryboard, useStoryboards
- **工具函数**: cn (Tailwind 样式合并)

## 后续优化

1. **拖拽排序**: 支持在资源总览中拖拽调整资源顺序
2. **批量操作**: 支持批量添加/删除资源
3. **资源标签**: 显示资源的更多元数据（类型、时长等）
4. **空状态优化**: 提供更友好的空状态提示和快捷操作
5. **键盘快捷键**: 支持键盘导航和操作