# 视频生成预检浮层重构

**日期**: 2026-02-03
**类型**: 功能优化
**影响范围**: 前端 - 分镜看板、预览面板

## 变更概述

将视频生成预检功能从 Dialog 弹窗改造为浮层组件，在点击视频轨道未生成视频的元素块时，在中间预览区域上方显示定位浮层。

## 主要变更

### 1. GenerationPrecheck 组件重构

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

- ✅ 移除 Dialog 和 DialogContent 依赖
- ✅ 改为使用固定定位的浮层 + 遮罩层实现
- ✅ 添加关闭按钮（X 图标）
- ✅ 添加 `onClose` 回调属性
- ✅ 使用 `animate-in` 动画效果（fade-in + zoom-in-95）
- ✅ 浮层居中显示，宽度 90vw（最大 4xl），高度 72vh

**接口变更**:
```typescript
// 旧接口
interface GenerationPrecheckProps {
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  // ...
}

// 新接口
interface GenerationPrecheckProps {
  open?: boolean;
  onClose?: () => void;
  // ...
}
```

### 2. EditorStore 状态管理

**文件**: `client/src/stores/editorStore.ts`

新增状态：
- `videoGenerationPrecheckOpen: boolean` - 浮层显示状态
- `videoGenerationPrecheckStoryboardId: string | null` - 当前预检的分镜 ID

新增方法：
- `openVideoGenerationPrecheck(storyboardId: string)` - 打开预检浮层
- `closeVideoGenerationPrecheck()` - 关闭预检浮层

### 3. CenterArea 布局集成

**文件**: `client/src/components/layout/CenterArea.tsx`

- ✅ 导入 GenerationPrecheck 组件
- ✅ 导入 useStoryboards 和 useResources hooks
- ✅ 根据 `videoGenerationPrecheckStoryboardId` 查找对应分镜
- ✅ 在 PreviewPanel 同级渲染浮层组件
- ✅ 传递分镜数据、资源数据和关闭回调

### 4. StoryboardBoardTrack 点击事件

**文件**: `client/src/components/features/storyboard-board/StoryboardBoardTrack.tsx`

- ✅ 移除 VideoGenerationPopover 导入
- ✅ 导入 useEditorStore 获取 `openVideoGenerationPrecheck` 方法
- ✅ 为视频轨道占位块添加 `onClick` 事件
- ✅ 点击时调用 `openVideoGenerationPrecheck(storyboardId)`

### 5. 删除冗余组件

**删除文件**: `client/src/components/features/storyboard-board/VideoGenerationPopover.tsx`

原因：功能已被 GenerationPrecheck 浮层替代，避免代码重复。

## 技术细节

### 浮层定位方案

使用 CSS 固定定位实现全局浮层：

```tsx
{/* 遮罩层 */}
<div className="fixed inset-0 bg-black/50 backdrop-blur-sm z-40" />

{/* 浮层内容 */}
<div className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 z-50">
  <GenerationPrecheckContent />
</div>
```

### 状态流转

1. 用户点击视频轨道占位块
2. 触发 `openVideoGenerationPrecheck(storyboardId)`
3. EditorStore 更新状态：`videoGenerationPrecheckOpen = true`
4. CenterArea 检测到状态变化，渲染浮层
5. 用户点击关闭按钮或遮罩层
6. 触发 `closeVideoGenerationPrecheck()`
7. 浮层隐藏

## 用户体验改进

### 优点

1. **更好的视觉层级**: 浮层覆盖在预览区域上方，视觉焦点更集中
2. **更灵活的定位**: 不受触发元素位置限制，始终居中显示
3. **更统一的交互**: 移除了 Popover 和 Dialog 两种不同的交互方式
4. **更清晰的关闭方式**: 提供明确的关闭按钮和遮罩层点击关闭

### 交互流程

```
分镜看板视频轨道
    ↓ 点击未生成视频的占位块
预览区域上方显示浮层
    ↓ 查看资源就绪状态
    ↓ 点击关闭按钮或遮罩层
浮层关闭
```

## 测试建议

### 功能测试

1. ✅ 点击视频轨道占位块，浮层正确显示
2. ✅ 浮层显示正确的分镜资源信息
3. ✅ 点击关闭按钮，浮层关闭
4. ✅ 点击遮罩层，浮层关闭
5. ✅ 浮层动画效果流畅

### 边界测试

1. ✅ 分镜无资源时，浮层正常显示
2. ✅ 快速切换不同分镜，浮层内容正确更新
3. ✅ 浮层打开时，背景内容不可交互

### 兼容性测试

1. ✅ TypeScript 类型检查通过
2. ✅ 不同屏幕尺寸下浮层正确居中
3. ✅ 浮层内容滚动正常

## 后续优化建议

1. **添加键盘快捷键**: 支持 ESC 键关闭浮层
2. **添加操作按钮**: 在浮层中添加"去定稿"、"立即生成"等操作按钮
3. **显示视频版本列表**: 恢复底部视频版本缩略图列表功能
4. **添加加载状态**: 分镜数据加载时显示骨架屏

## 相关文件

### 修改文件
- `client/src/components/features/preview/GenerationPrecheck.tsx`
- `client/src/stores/editorStore.ts`
- `client/src/components/layout/CenterArea.tsx`
- `client/src/components/features/storyboard-board/StoryboardBoardTrack.tsx`

### 删除文件
- `client/src/components/features/storyboard-board/VideoGenerationPopover.tsx`

## 版本信息

- **前端框架**: React 19 + TypeScript
- **状态管理**: Zustand
- **UI 组件**: shadcn/ui
- **动画**: Tailwind CSS animate-in utilities