Genarrative/docs/technical/PUZZLE_RESULT_FORMAL_IMAGE_REFRESH_FIX_2026-04-27.md

拼图结果页正式图刷新修复

日期：2026-04-27

背景

拼图结果页点击“生成并替换当前图片”后，后端会返回最新 session，并把新图片写回 draft.coverImageSrc。但前端正式图展示仍可能命中旧的签名 URL 或浏览器图片缓存，导致当前正式图看起来没有变化。

这个问题在 /generated-puzzle-assets/... 私有资源链路下尤其明显：

1. 结果页展示依赖 ResolvedAssetImage -> useResolvedAssetReadUrl -> /api/assets/read-url
2. 读地址服务会缓存同一路径的签名 URL
3. 如果同一路径对应的资源内容在短时间内被更新，页面可能继续显示旧图

修复口径

1. src/services/assetReadUrlService.ts
   • 为 resolveAssetReadUrl(...) 增加 refreshKey
   • 当调用方显式传入 refreshKey 时，跳过本地签名缓存
   • 在最终图片 URL 上追加 _v 参数，强制浏览器拉取当前版本
2. src/components/ResolvedAssetImage.tsx
   • 支持透传 refreshKey
3. src/components/puzzle-result/PuzzleResultView.tsx
   • 拼图结果页正式图与发布弹窗正式图统一使用 session.updatedAt + coverImageSrc 作为刷新锚点
   • 保证每次“生成并替换当前图片”回写新 session 后，结果页主图和发布预览图都会同步刷新

回归验证

1. src/hooks/useResolvedAssetReadUrl.test.tsx
   • 新增 refreshKey 变化时重新获取签名地址并带 _v 参数的测试
2. src/components/puzzle-result/PuzzleResultView.test.tsx
   • 新增 session 更新后正式图切换到新 coverImageSrc 的回归测试

后续约束

1. 任何使用 /generated-* 私有资源且存在“同一业务位重复生成替换”的界面，都应明确是否需要 refreshKey
2. 如果后端后续改成稳定对象键覆写，也不能移除前端结果页的主动刷新锚点