1

docs/technical/PUZZLE_RESULT_FORMAL_IMAGE_REFRESH_FIX_2026-04-27.md

@@ -0,0 +1,37 @@
+# 拼图结果页正式图刷新修复
+
+日期：`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. 如果后端后续改成稳定对象键覆写，也不能移除前端结果页的主动刷新锚点