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