# RFC 133: 预览信息面板组件

## 元数据

- **状态**: 已实施
- **创建日期**: 2026-01-28
- **实施日期**: 2026-01-28
- **作者**: Kiro AI
- **类型**: 新功能

## 概述

为 SingleViewPlayer 组件创建可展开的信息面板，支持分镜、角色、场景、道具、实拍等多种类型的详细信息展示和编辑。

## 背景

### 现状

当前 SingleViewPlayer 组件的信息浮层功能有限：
- 仅显示标题和描述
- 无交互功能
- 无法展示详细信息
- 不支持编辑

### 问题

1. 用户无法查看完整的分镜/资源详细信息
2. 无法在预览界面直接编辑信息
3. 不同类型的内容需要不同的字段展示
4. 信息展示不够直观和美观

## 目标

1. 创建独立的 PreviewInfoPanel 组件
2. 支持展开/收起动画
3. 支持 5 种类型的内容展示
4. 支持编辑模式
5. 使用纯 CSS 动画，无需额外依赖

## 设计方案

### 组件架构

```
PreviewInfoPanel
├── 收起状态（默认）
│   ├── 标题（支持多状态）
│   ├── 描述（1行截断）
│   └── 展开按钮
└── 展开状态
    ├── 完整标题和描述
    ├── 详细字段（根据类型）
    ├── 编辑按钮
    └── 收起按钮
```

### 视觉设计

**收起状态**：
- 高度：80px
- 背景：`bg-linear-to-t from-black/80 to-transparent`
- 定位：`absolute bottom-0 left-0 right-0`
- 内容：标题 + 描述（1行）

**展开状态**：
- 高度：撑满图片容器（`absolute top-0 bottom-0`）
- 背景：`bg-black/90 backdrop-blur-xl`
- 内容：完整信息 + 可滚动
- 编辑模式：表单字段 + 保存/取消按钮

**动画**：
```css
transition: all 300ms ease-out
```

### 数据类型

```typescript
// 分镜数据
interface StoryboardData {
  shotNumber: string;      // 镜号
  title: string;           // 标题
  description: string;     // 内容描述
  shotSize?: string;       // 景别
  cameraMovement?: string; // 运镜
  dialogue?: string;       // 对白
}

// 角色数据
interface CharacterData {
  name: string;            // 角色名称
  costume?: string;        // 装扮
  gender?: string;         // 性别
  age?: string;            // 年龄
  occupation?: string;     // 职业
  roleType?: string;       // 主角类型
  personality?: string;    // 性格
  appearance?: string;     // 外貌特征
  voiceModel?: string;     // 声音模型
  description?: string;    // 简介
}

// 场景数据
interface SceneData {
  name: string;                // 场景名称
  setting?: string;            // 布景
  locationType?: string;       // 场景类型
  timeOfDay?: string;          // 时间
  weather?: string;            // 天气
  atmosphere?: string;         // 氛围
  realWorldLocation?: string;  // 现实取景地
  description?: string;        // 简介
}

// 道具数据
interface PropData {
  name: string;          // 道具名称
  status?: string;       // 状态
  propType?: string;     // 道具类型
  usage?: string;        // 用途
  quantity?: number;     // 数量
  size?: string;         // 尺寸
  description?: string;  // 简介
}

// 实拍数据
interface FootageData {
  name: string;          // 实拍名称
  duration?: string;     // 时长
  format?: string;       // 格式
  description?: string;  // 简介
}
```

### 组件接口

```typescript
interface PreviewInfoPanelProps {
  type: 'storyboard' | 'character' | 'scene' | 'prop' | 'footage';
  data: PreviewData;
  onUpdate?: (data: PreviewData) => void;
}
```

## 实施细节

### 1. 组件创建

**文件**: `client/src/components/features/preview/PreviewInfoPanel.tsx`

**核心功能**：
- 展开/收起状态管理
- 编辑模式切换
- 表单数据处理
- 类型化内容渲染

### 2. 动画实现

使用纯 CSS transition：
```tsx
className={cn(
  'absolute left-0 right-0 bottom-0 transition-all duration-300 ease-out',
  isExpanded ? 'top-0' : 'h-20'
)}
```

### 3. 内容渲染

根据 `type` 属性渲染不同的字段：
- `renderStoryboardFields()` - 分镜信息
- `renderCharacterFields()` - 角色信息
- `renderSceneFields()` - 场景信息
- `renderPropFields()` - 道具信息
- `renderFootageFields()` - 实拍信息

### 4. 编辑模式

- 点击编辑按钮激活编辑模式
- 表单字段使用 Input/Textarea/Select 组件
- 保存时调用 `onUpdate` 回调
- 取消时恢复原始数据

### 5. 集成到 SingleViewPlayer

```tsx
<PreviewInfoPanel
  type={currentItem.type || 'storyboard'}
  data={{
    shotNumber: currentItem.shotNumber || '',
    title: currentItem.title,
    description: currentItem.description,
    // ... 其他字段
  }}
  onUpdate={(data) => {
    console.log('更新信息:', data);
    // TODO: 调用实际的更新 API
  }}
/>
```

## 技术选型

### 动画方案

**选择**: 纯 CSS Transition

**理由**：
- ✅ 零依赖，不增加包体积
- ✅ 性能优秀
- ✅ 满足需求（简单的展开/收起）
- ✅ 符合项目现有技术栈

**备选**: Framer Motion
- ❌ 需要安装依赖（~60KB）
- ✅ 动画控制更灵活
- ⚠️ 对当前需求来说过度设计

### UI 组件

使用项目现有的 shadcn/ui 组件：
- Input - 文本输入
- Textarea - 多行文本
- Select - 下拉选择
- Button - 按钮
- ScrollArea - 滚动区域

## 影响范围

### 修改的文件

1. **client/src/components/features/preview/SingleViewPlayer.tsx**
   - 导入 PreviewInfoPanel 组件
   - 替换原有信息浮层
   - 扩展 StoryboardItem 接口

2. **client/src/components/features/preview/PreviewInfoPanel.tsx** (新建)
   - 完整的信息面板组件实现

### 类型定义更新

扩展 `StoryboardItem` 接口：
```typescript
interface StoryboardItem {
  id: string;
  title: string;
  description: string;
  thumbnailUrl: string;
  // 新增字段
  shotNumber?: string;
  shotSize?: string;
  cameraMovement?: string;
  dialogue?: string;
  type?: 'storyboard' | 'character' | 'scene' | 'prop' | 'footage';
}
```

## 测试计划

### 功能测试

1. **展开/收起动画**
   - 点击按钮正常展开
   - 点击按钮正常收起
   - 动画流畅无卡顿

2. **内容展示**
   - 分镜信息正确显示
   - 角色信息正确显示
   - 场景信息正确显示
   - 道具信息正确显示
   - 实拍信息正确显示

3. **编辑模式**
   - 点击编辑按钮进入编辑模式
   - 表单字段可正常输入
   - 保存后数据更新
   - 取消后恢复原始数据

4. **响应式**
   - 不同屏幕尺寸下正常显示
   - 滚动功能正常

### 性能测试

1. 动画性能（60fps）
2. 大量字段时的渲染性能
3. 编辑模式切换性能

## 后续优化

1. **数据持久化**
   - 集成后端 API
   - 实现自动保存
   - 添加加载状态

2. **增强功能**
   - 支持快捷键（Esc 关闭、Enter 保存）
   - 添加字段验证
   - 支持撤销/重做

3. **视觉优化**
   - 添加微动画
   - 优化字段布局
   - 支持主题切换

4. **可访问性**
   - 键盘导航支持
   - 屏幕阅读器支持
   - ARIA 属性完善

## 风险评估

### 低风险

- ✅ 使用现有技术栈
- ✅ 独立组件，不影响其他功能
- ✅ 纯 CSS 动画，兼容性好

### 需要注意

- ⚠️ 不同类型的字段较多，需要仔细测试
- ⚠️ 编辑模式的数据同步需要处理好
- ⚠️ 后续需要集成后端 API

## 参考资料

- [ResourceProfileTab 组件](../../../client/src/components/features/preview/tabs/ResourceProfileTab.tsx) - 字段展示参考
- [Tailwind CSS Transitions](https://tailwindcss.com/docs/transition-property)
- [React Hook Form](https://react-hook-form.com/) - 未来可能的表单优化方案

## 总结

PreviewInfoPanel 组件为预览界面提供了强大的信息展示和编辑能力，通过纯 CSS 动画实现流畅的交互体验，支持多种类型的内容展示，为用户提供了更好的使用体验。