48 lines
2.7 KiB
Markdown
48 lines
2.7 KiB
Markdown
## 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 说明原因
|
||
- 保存该结果到素材库：素材卡片应保留角标
|
||
- 已缓存成功的素材：不应显示缓存失败角标
|
||
- 未进行缓存或没有失败记录的历史资源：不应仅凭模型名显示角标
|