Initial TrueGrowth source import
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
## Context
|
||||
项目里已存在三类视频预览来源：
|
||||
- 任务结果自带 `previewImageUrl` / `thumbnail`
|
||||
- Service Worker 为缓存媒体生成 `?thumbnail=` 预览图
|
||||
- 无法生成首帧时只能直接依赖 `<video>`
|
||||
|
||||
现状问题不在“完全没有能力”，而在于展示入口未统一复用，导致素材库等高频列表仍走原生 video 首次解码。
|
||||
|
||||
## Goals
|
||||
- 降低视频列表和卡片首次渲染成本
|
||||
- 不让跨域失败导致视频完全不可预览
|
||||
- 不破坏已有点击播放和原生控制条场景
|
||||
|
||||
## Non-Goals
|
||||
- 不改动视频分析器、画布视频节点等重交互播放内核
|
||||
- 不新增后端缩略图服务
|
||||
- 不强制为所有远程跨域视频生成首帧
|
||||
|
||||
## Decision
|
||||
采用统一策略：
|
||||
|
||||
1. 优先海报
|
||||
- 若业务已提供 `posterUrl` / `thumbnail` / `previewImageUrl`，优先直接展示
|
||||
- 否则对虚拟缓存 URL 使用现有 `useThumbnailUrl(..., 'video')`
|
||||
|
||||
2. 失败降级
|
||||
- 海报图加载失败时自动退回 `<video>`
|
||||
- 对远程跨域 URL，由于 `useThumbnailUrl` 会返回原视频地址，`img` 失败后自动退回 `<video>`
|
||||
|
||||
3. 交互分层
|
||||
- 列表、网格、时间线、任务卡片等场景：默认只展示海报，必要时仅保留播放 icon
|
||||
- 详情预览、嵌入卡片等可点击播放场景：默认海报，用户点击后切换到 `<video controls>`
|
||||
- 画布节点、分析工具主预览等必须即时播放/控制的场景：继续直接使用 `<video>`
|
||||
|
||||
## Risks
|
||||
- 某些样式只给 `video` 写了 class，需要同步兼容 `img`
|
||||
- 海报与视频尺寸不一致时可能出现裁切差异
|
||||
- 远程视频会先经历一次 `img` 失败再退回 `video`，需要避免闪烁过重
|
||||
|
||||
## Verification
|
||||
- 本地上传视频首次进入素材库，应优先看到海报而非黑屏或长时间等待
|
||||
- 远程跨域视频无法抽帧时，应自动退回 video，仍可预览/播放
|
||||
- 可播放详情场景点击海报后，应切换为可控制的 video
|
||||
@@ -0,0 +1,19 @@
|
||||
# Change: 优化视频展示为海报优先并保留可播放降级
|
||||
|
||||
## Why
|
||||
当前项目中多个视频列表/卡片场景直接渲染 `<video preload="metadata">`，导致素材库等页面首次展示慢。项目内已经存在视频首帧缩略图与 Cache Storage 基础能力，但接入不统一，且跨域失败时容易退化为“无预览”。
|
||||
|
||||
## What Changes
|
||||
- 统一视频缩略场景的展示策略为“海报图优先，失败再降级到 video”
|
||||
- 优先复用已有 `thumbnail`、`previewImageUrl` 与 `?thumbnail=` Service Worker 缓存能力
|
||||
- 在需要直接点击播放的场景支持“先海报、后切换 video 播放”
|
||||
- 对必须保留原生 `video` 的场景维持现状，避免交互回退
|
||||
|
||||
## Impact
|
||||
- Affected specs: `media-preview`
|
||||
- Affected code:
|
||||
- `packages/drawnix/src/components/media-library/*`
|
||||
- `packages/drawnix/src/components/shared/media-preview/*`
|
||||
- `packages/drawnix/src/components/task-queue/*`
|
||||
- `packages/drawnix/src/components/MarkdownEditor/asset-embed-plugin/*`
|
||||
- `packages/drawnix/src/components/shared/SelectedContentPreview.tsx`
|
||||
@@ -0,0 +1,28 @@
|
||||
## ADDED 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** 用户可正常播放该视频
|
||||
@@ -0,0 +1,7 @@
|
||||
## 1. Implementation
|
||||
- [x] 1.1 盘点所有视频展示入口，按“缩略场景 / 直接播放场景”分类
|
||||
- [x] 1.2 抽取统一的视频海报预览组件，支持已有 poster、缓存缩略图、失败回退到 video
|
||||
- [x] 1.3 替换素材库、缩略队列、任务卡片等非直接播放场景
|
||||
- [x] 1.4 替换需要点击播放但可先展示海报的场景
|
||||
- [x] 1.5 保持分析器、画布节点等必须原生播放的场景不变
|
||||
- [x] 1.6 验证跨域视频、无缩略图视频、本地缓存视频三类行为
|
||||
Reference in New Issue
Block a user