Initial TrueGrowth source import
This commit is contained in:
@@ -0,0 +1,47 @@
|
||||
## Context
|
||||
部分远程媒体 URL 可直接展示，但不允许前端读取响应体，或在缓存流程中因网络、响应类型、浏览器策略等原因失败。此时浏览器 Cache Storage / IndexedDB 无法保存稳定副本，只能继续依赖原始远程链接；如果链接带签名有效期，用户之后可能无法再次访问。
|
||||
|
||||
现有项目已有统一缓存服务、任务队列、素材库下载能力和 HoverTip 组件。本次需求重点是把“缓存失败且链接可能过期”显性化，而不是按模型或供应商做特殊分支。
|
||||
|
||||
## Goals
|
||||
- 用户能在素材库和任务队列快速识别需要尽快下载的素材
|
||||
- hover 能解释“未能缓存到浏览器、原始链接可能过期”
|
||||
- 提示逻辑与模型无关，只取决于缓存结果和缓存状态
|
||||
- 不阻塞列表渲染，不批量发起跨域探测请求
|
||||
- 与现有下载按钮、素材保存、缓存状态兼容
|
||||
|
||||
## Non-Goals
|
||||
- 不绕过 CORS、签名 URL 或浏览器缓存限制
|
||||
- 不新增后端转存/代理下载服务
|
||||
- 不按模型名、供应商名、URL 域名硬编码判断是否提示
|
||||
- 不保证所有历史素材都能精确判断链接有效期
|
||||
- 不改变任务生成与下载主流程
|
||||
|
||||
## Decision
|
||||
采用“缓存结果驱动”的设计：
|
||||
|
||||
1. 数据状态
|
||||
- 新增可选 `cacheWarning` 元数据，挂在 `TaskResult`、`Asset`、`StoredAsset` 等媒体结果上
|
||||
- 字段只保存短文本和枚举，例如 `reasonCode`、`message`、`detectedAt`、`expiresHint`
|
||||
- 缓存服务在明确失败时生成标准化失败结果，由任务和素材保存流程透传
|
||||
|
||||
2. UI 展示
|
||||
- 素材库卡片显示黄色角标，例如“需下载”
|
||||
- 任务队列完成态媒体结果显示同类角标
|
||||
- HoverTip 文案统一：资源未能缓存到浏览器，原始链接可能过期，请尽快下载保存；并展示具体缓存失败原因
|
||||
|
||||
3. 判断边界
|
||||
- 只在已有缓存流程返回失败、缓存状态为错误、或媒体对象已携带 `cacheWarning` 时展示角标
|
||||
- 已缓存成功的媒体优先以成功状态为准，不展示缓存失败提示
|
||||
- 对没有缓存尝试记录的历史远程资源，不凭模型名或供应商名推断失败，避免误报
|
||||
|
||||
## Risks
|
||||
- 历史资源如果没有缓存失败记录，可能不会显示提示
|
||||
- 需要确保缓存失败原因能从缓存服务可靠透传到任务和素材
|
||||
- 若角标过多可能干扰卡片视觉，需要沿用现有 badge 层级和 HoverTip
|
||||
|
||||
## Verification
|
||||
- 模拟缓存失败的图片任务：任务队列应显示角标，hover 说明原因
|
||||
- 保存该结果到素材库：素材卡片应保留角标
|
||||
- 已缓存成功的素材：不应显示缓存失败角标
|
||||
- 未进行缓存或没有失败记录的历史资源：不应仅凭模型名显示角标
|
||||
@@ -0,0 +1,21 @@
|
||||
# Change: 为缓存失败素材增加尽快下载提示角标
|
||||
|
||||
## Why
|
||||
部分远程图片/视频素材可以直接预览，但浏览器未必能稳定写入本地缓存；如果原始链接带签名有效期，用户之后可能无法再次访问。当前用户在素材库或任务队列中看到资源可预览时，容易误以为已离线保存，等链接过期后才发现素材不可恢复。
|
||||
|
||||
## What Changes
|
||||
- 为媒体缓存失败或不可缓存的任务结果与素材增加轻量警告状态
|
||||
- 在素材库卡片和任务队列卡片显示“需下载/缓存失败”角标
|
||||
- hover 角标时说明原因，并提示用户尽快下载保存
|
||||
- 提示逻辑只依据缓存结果与缓存状态，不依据模型名或供应商名判断
|
||||
- 不对列表资源做额外跨域探测，避免增加渲染成本和网络压力
|
||||
|
||||
## Impact
|
||||
- Affected specs: `media-cache-warnings`
|
||||
- Affected code:
|
||||
- `packages/drawnix/src/types/asset.types.ts`
|
||||
- `packages/drawnix/src/types/shared/core.types.ts`
|
||||
- `packages/drawnix/src/services/unified-cache-service.ts`
|
||||
- `packages/drawnix/src/services/task-queue-service.ts`
|
||||
- `packages/drawnix/src/components/media-library/*`
|
||||
- `packages/drawnix/src/components/task-queue/*`
|
||||
@@ -0,0 +1,55 @@
|
||||
## ADDED Requirements
|
||||
### Requirement: 缓存失败媒体必须携带下载提醒状态
|
||||
系统 SHALL 为浏览器缓存失败或已知不可缓存的远程图片/视频结果记录可选警告状态，用于提示用户尽快下载保存。
|
||||
|
||||
#### Scenario: 远程媒体缓存失败
|
||||
- **GIVEN** 图片或视频任务结果已生成远程 URL
|
||||
- **AND** 浏览器缓存流程因跨域、网络或响应不可读而失败
|
||||
- **WHEN** 系统更新任务结果或保存素材
|
||||
- **THEN** 该媒体应携带缓存警告状态
|
||||
- **AND** 警告状态应包含可展示原因和检测时间
|
||||
|
||||
### Requirement: 素材库必须展示缓存失败角标
|
||||
系统 SHALL 在素材库中为携带缓存警告或缓存状态明确为失败的图片/视频素材显示可见角标。
|
||||
|
||||
#### Scenario: 用户浏览缓存失败素材
|
||||
- **GIVEN** 素材库中某图片或视频未能缓存到浏览器
|
||||
- **WHEN** 用户打开素材库并看到该素材卡片
|
||||
- **THEN** 卡片应显示“需下载”或等价语义角标
|
||||
- **AND** 用户 hover 角标时应看到无法缓存与链接可能过期的说明
|
||||
|
||||
### Requirement: 任务队列必须展示缓存失败角标
|
||||
系统 SHALL 在任务队列完成态媒体结果中为缓存失败或缓存状态明确为错误的图片/视频显示可见角标。
|
||||
|
||||
#### Scenario: 用户查看刚完成且缓存失败的视频任务
|
||||
- **GIVEN** 视频任务已完成并返回可预览远程 URL
|
||||
- **AND** 该 URL 未能缓存到浏览器
|
||||
- **WHEN** 用户查看任务队列结果卡片
|
||||
- **THEN** 结果卡片应显示下载提醒角标
|
||||
- **AND** hover 角标时应提示用户尽快下载保存
|
||||
|
||||
### Requirement: 提醒判断必须与模型无关
|
||||
系统 SHALL 只根据缓存结果、缓存状态或媒体对象上的缓存警告决定是否展示下载提醒，不得根据模型名、供应商名或 URL 域名硬编码判断。
|
||||
|
||||
#### Scenario: 不同模型产生相同缓存失败结果
|
||||
- **GIVEN** 两个不同模型生成的媒体都发生浏览器缓存失败
|
||||
- **WHEN** 用户在素材库或任务队列查看这些媒体
|
||||
- **THEN** 两个媒体都应显示缓存失败下载提醒
|
||||
- **AND** 提醒文案不应依赖具体模型名称
|
||||
|
||||
### Requirement: 提醒判断不得主动批量探测跨域资源
|
||||
系统 SHALL 使用已有缓存状态和任务结果元数据来决定是否展示提醒，不得在列表渲染期间对每个远程资源发起额外跨域探测请求。
|
||||
|
||||
#### Scenario: 用户打开包含大量远程素材的素材库
|
||||
- **GIVEN** 素材库中存在大量远程图片和视频
|
||||
- **WHEN** UI 渲染素材列表
|
||||
- **THEN** 系统不应为了判断角标而批量 fetch 远程资源
|
||||
- **AND** 列表渲染不应被缓存检测阻塞
|
||||
|
||||
### Requirement: 已成功缓存的媒体不得显示缓存失败角标
|
||||
系统 SHALL 对已确认缓存成功的图片/视频隐藏缓存失败下载提醒，避免误导用户。
|
||||
|
||||
#### Scenario: 用户浏览已离线缓存的素材
|
||||
- **GIVEN** 某图片或视频已成功写入浏览器缓存
|
||||
- **WHEN** 用户在素材库或任务队列查看该媒体
|
||||
- **THEN** 系统不应显示缓存失败或尽快下载角标
|
||||
@@ -0,0 +1,8 @@
|
||||
## 1. Implementation
|
||||
- [x] 1.1 梳理任务结果到素材库保存链路，确认警告元数据透传点
|
||||
- [x] 1.2 扩展媒体类型定义，新增可选缓存警告字段
|
||||
- [x] 1.3 在统一缓存失败路径生成标准化警告原因
|
||||
- [x] 1.4 在任务队列完成态媒体卡片显示角标与 HoverTip
|
||||
- [x] 1.5 在素材库卡片显示角标与 HoverTip
|
||||
- [x] 1.6 确保提示判断只依赖缓存结果，不依赖模型或供应商
|
||||
- [x] 1.7 验证缓存成功、缓存失败、无缓存记录三类展示
|
||||
Reference in New Issue
Block a user