# media-preview Specification

## Purpose
TBD - created by archiving change update-video-poster-preview-fallback. Update Purpose after archive.
## Requirements
### Requirement: 视频展示必须优先使用海报预览
系统 SHALL 在列表、网格、缩略图等非必须即时播放的视频展示场景中优先使用图片海报，而不是首次直接渲染视频内容。

#### Scenario: 缓存视频首次出现在素材库列表
- **GIVEN** 视频资源已缓存到本地虚拟路径
- **WHEN** 用户首次打开素材库或滚动到该素材
- **THEN** 界面应优先请求该视频对应的海报图
- **AND** 不应依赖首次解码 `<video>` 作为默认展示路径

### Requirement: 海报失败时必须回退到视频预览
系统 SHALL 在视频海报不可用或加载失败时自动回退到原生视频预览，避免出现“完全不可预览”的状态。

#### Scenario: 跨域视频无法生成首帧
- **GIVEN** 视频资源因跨域限制无法提取首帧或海报图加载失败
- **WHEN** 页面尝试展示该视频
- **THEN** 系统应自动改用 `<video>` 进行预览
- **AND** 用户仍可看到该视频内容或继续播放

### Requirement: 可点击播放场景必须支持先海报后播放
系统 SHALL 在允许用户直接播放视频的详情或预览场景中支持先显示海报，再在用户触发后切换为原生视频播放器。

#### Scenario: 详情面板中的视频点击播放
- **GIVEN** 某视频展示场景支持用户直接点击播放
- **WHEN** 海报图已成功展示
- **AND** 用户点击该海报
- **THEN** 系统应切换为原生 `<video controls>`
- **AND** 用户可正常播放该视频