fix(chat-media): 修复聊天图片缓存降级并刷新当前会话媒体

2977094657 · 2977094657 · commit dc112e7d151f · 2026-03-30T22:02:09.000+08:00
- 优先使用更高质量的微信图片资源并回写本地缓存
- 图片接口返回 no-store，避免浏览器继续命中旧缓存
- 页面恢复前台时刷新当前会话媒体资源，并补充相关测试
diff --git a/frontend/composables/chat/useChatMessages.js b/frontend/composables/chat/useChatMessages.js
@@ -74,6 +74,7 @@ export const useChatMessages = ({
   let highlightTimer = null
 
   const messageTypeFilter = ref('all')
+  const localMediaVersion = ref(0)
   const messageTypeFilterOptions = [
     { value: 'all', label: '全部' },
     { value: 'text', label: '文本' },
@@ -95,9 +96,39 @@ export const useChatMessages = ({
   const normalizeMessage = createMessageNormalizer({
     apiBase,
     getSelectedAccount: () => selectedAccount.value,
-    getSelectedContact: () => selectedContact.value
+    getSelectedContact: () => selectedContact.value,
+    getLocalMediaVersion: () => localMediaVersion.value
   })
 
+  const bumpLocalMediaVersion = () => {
+    localMediaVersion.value = (localMediaVersion.value + 1) % 1000000000
+    return localMediaVersion.value
+  }
+
+  const renormalizeLoadedMessages = (username) => {
+    const key = String(username || '').trim()
+    if (!key) return
+    const existing = allMessages.value[key]
+    if (!Array.isArray(existing) || !existing.length) return
+
+    const refreshed = dedupeMessagesById(existing.map((message) => {
+      const normalized = normalizeMessage(message)
+      return {
+        ...message,
+        ...normalized,
+        _emojiDownloading: !!message?._emojiDownloading,
+        _emojiDownloaded: typeof message?._emojiDownloaded === 'boolean' ? message._emojiDownloaded : normalized._emojiDownloaded,
+        _quoteImageError: false,
+        _quoteThumbError: false
+      }
+    }))
+
+    allMessages.value = {
+      ...allMessages.value,
+      [key]: refreshed
+    }
+  }
+
   const messages = computed(() => {
     if (!selectedContact.value) return []
     return allMessages.value[selectedContact.value.username] || []
@@ -534,9 +565,17 @@ export const useChatMessages = ({
 
   const refreshSelectedMessages = async () => {
     if (!selectedContact.value) return
+    bumpLocalMediaVersion()
     await loadMessages({ username: selectedContact.value.username, reset: true })
   }
 
+  const refreshCurrentMessageMedia = async () => {
+    if (!selectedContact.value?.username) return
+    bumpLocalMediaVersion()
+    renormalizeLoadedMessages(selectedContact.value.username)
+    await nextTick()
+  }
+
   const refreshRealtimeIncremental = async () => {
     if (!realtimeEnabled.value || !selectedAccount.value || !selectedContact.value?.username) return
     if (searchContext.value?.active || isLoadingMessages.value) return
@@ -912,6 +951,7 @@ export const useChatMessages = ({
     loadMessages,
     loadMoreMessages,
     refreshSelectedMessages,
+    refreshCurrentMessageMedia,
     refreshRealtimeIncremental,
     queueRealtimeRefresh,
     tryEnableRealtimeAuto,
diff --git a/frontend/lib/chat/message-normalizer.js b/frontend/lib/chat/message-normalizer.js
@@ -17,11 +17,12 @@ const buildAccountMediaUrl = (apiBase, path, parts) => {
   return `${apiBase}${path}?${parts.filter(Boolean).join('&')}`
 }
 
-export const createMessageNormalizer = ({ apiBase, getSelectedAccount, getSelectedContact }) => {
+export const createMessageNormalizer = ({ apiBase, getSelectedAccount, getSelectedContact, getLocalMediaVersion }) => {
   return (msg) => {
     const account = String(getSelectedAccount?.() || '').trim()
     const contact = getSelectedContact?.() || null
     const username = String(contact?.username || '').trim()
+    const localMediaVersion = Number(getLocalMediaVersion?.() || 0)
     const isSent = !!msg.isSent
     const sender = isSent ? '我' : (msg.senderDisplayName || msg.senderUsername || contact?.name || '')
     const fallbackAvatar = (!isSent && !contact?.isGroup) ? (contact?.avatar || null) : null
@@ -66,7 +67,8 @@ export const createMessageNormalizer = ({ apiBase, getSelectedAccount, getSelect
         `account=${encodeURIComponent(account)}`,
         msg.imageMd5 ? `md5=${encodeURIComponent(msg.imageMd5)}` : '',
         msg.imageFileId ? `file_id=${encodeURIComponent(msg.imageFileId)}` : '',
-        `username=${encodeURIComponent(username)}`
+        `username=${encodeURIComponent(username)}`,
+        localMediaVersion > 0 ? `v=${encodeURIComponent(String(localMediaVersion))}` : ''
       ])
     })()
 
@@ -86,7 +88,8 @@ export const createMessageNormalizer = ({ apiBase, getSelectedAccount, getSelect
         `account=${encodeURIComponent(account)}`,
         msg.videoThumbMd5 ? `md5=${encodeURIComponent(msg.videoThumbMd5)}` : '',
         msg.videoThumbFileId ? `file_id=${encodeURIComponent(msg.videoThumbFileId)}` : '',
-        `username=${encodeURIComponent(username)}`
+        `username=${encodeURIComponent(username)}`,
+        localMediaVersion > 0 ? `v=${encodeURIComponent(String(localMediaVersion))}` : ''
       ])
     })()
 
@@ -158,7 +161,8 @@ export const createMessageNormalizer = ({ apiBase, getSelectedAccount, getSelect
       return buildAccountMediaUrl(apiBase, '/chat/media/image', [
         `account=${encodeURIComponent(account)}`,
         `server_id=${encodeURIComponent(quoteServerIdStr)}`,
-        username ? `username=${encodeURIComponent(username)}` : ''
+        username ? `username=${encodeURIComponent(username)}` : '',
+        localMediaVersion > 0 ? `v=${encodeURIComponent(String(localMediaVersion))}` : ''
       ])
     })()
 
diff --git a/frontend/pages/chat/[[username]].vue b/frontend/pages/chat/[[username]].vue
@@ -216,6 +216,7 @@ const {
   loadMessages,
   loadMoreMessages,
   refreshSelectedMessages,
+  refreshCurrentMessageMedia,
   queueRealtimeRefresh,
   tryEnableRealtimeAuto,
   resetMessageState,
@@ -568,6 +569,28 @@ const onGlobalKeyDown = (event) => {
   }
 }
 
+let lastResumeMediaRefreshAt = 0
+
+const maybeRefreshMediaOnResume = () => {
+  if (!process.client) return
+  if (!selectedContact.value?.username) return
+  if (searchContext.value?.active) return
+
+  const now = Date.now()
+  if ((now - lastResumeMediaRefreshAt) < 1200) return
+  lastResumeMediaRefreshAt = now
+  void refreshCurrentMessageMedia()
+}
+
+const onWindowFocus = () => {
+  maybeRefreshMediaOnResume()
+}
+
+const onVisibilityChange = () => {
+  if (document.visibilityState !== 'visible') return
+  maybeRefreshMediaOnResume()
+}
+
 onMounted(async () => {
   if (!process.client) return
 
@@ -585,6 +608,8 @@ onMounted(async () => {
   document.addEventListener('touchmove', onFloatingWindowMouseMove)
   document.addEventListener('touchend', onFloatingWindowMouseUp)
   document.addEventListener('touchcancel', onFloatingWindowMouseUp)
+  window.addEventListener('focus', onWindowFocus)
+  document.addEventListener('visibilitychange', onVisibilityChange)
 
   logChatBootstrap('loadContacts:start', {
     selectedAccount: selectedAccount.value
@@ -635,6 +660,8 @@ onUnmounted(() => {
   document.removeEventListener('touchmove', onFloatingWindowMouseMove)
   document.removeEventListener('touchend', onFloatingWindowMouseUp)
   document.removeEventListener('touchcancel', onFloatingWindowMouseUp)
+  window.removeEventListener('focus', onWindowFocus)
+  document.removeEventListener('visibilitychange', onVisibilityChange)
 
   if (locateServerIdTimer) clearTimeout(locateServerIdTimer)
   locateServerIdTimer = null
diff --git a/src/wechat_decrypt_tool/routers/chat_media.py b/src/wechat_decrypt_tool/routers/chat_media.py
@@ -67,6 +67,87 @@
 router = APIRouter(route_class=PathFixRoute)
 
 
+def _build_uncached_media_response(data: bytes, media_type: str) -> Response:
+    resp = Response(content=data, media_type=media_type)
+    resp.headers["Cache-Control"] = "no-store"
+    return resp
+
+
+def _image_candidate_variant_rank(path: Path) -> int:
+    stem = str(path.stem or "").lower()
+    if stem.endswith(("_b", ".b")):
+        return 0
+    if stem.endswith(("_h", ".h")):
+        return 1
+    if stem.endswith(("_c", ".c")):
+        return 3
+    if stem.endswith(("_t", ".t")):
+        return 4
+    return 2
+
+
+def _image_candidate_stat(path: Optional[Path]) -> tuple[int, float]:
+    if not path:
+        return 0, 0.0
+    try:
+        st = path.stat()
+        return int(st.st_size), float(st.st_mtime)
+    except Exception:
+        return 0, 0.0
+
+
+def _should_prefer_live_image_candidates(
+    *,
+    cached_path: Optional[Path],
+    live_candidates: list[Path],
+) -> bool:
+    if not live_candidates:
+        return False
+    if not cached_path:
+        return True
+
+    best_live = live_candidates[0]
+    live_rank = _image_candidate_variant_rank(best_live)
+    if live_rank < 2:
+        return True
+
+    cache_size, cache_mtime = _image_candidate_stat(cached_path)
+    live_size, live_mtime = _image_candidate_stat(best_live)
+    if live_rank == 2 and live_size > cache_size:
+        return True
+    if live_rank == 2 and live_size >= cache_size and live_mtime > cache_mtime:
+        return True
+    return False
+
+
+def _write_cached_chat_image(account_dir: Path, md5: str, data: bytes) -> None:
+    md5_norm = str(md5 or "").strip().lower()
+    if (not md5_norm) or (not data):
+        return
+
+    ext = _detect_image_extension(data)
+    out_path = _get_decrypted_resource_path(account_dir, md5_norm, ext)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    for stale_ext in ("jpg", "png", "gif", "webp", "dat"):
+        stale_path = _get_decrypted_resource_path(account_dir, md5_norm, stale_ext)
+        if stale_path == out_path:
+            continue
+        try:
+            if stale_path.exists():
+                stale_path.unlink()
+        except Exception:
+            pass
+
+    try:
+        if out_path.exists() and out_path.read_bytes() == data:
+            return
+    except Exception:
+        pass
+
+    out_path.write_bytes(data)
+
+
 def _resolve_avatar_remote_url(*, account_dir: Path, username: str) -> str:
     u = str(username or "").strip()
     if not u:
@@ -1311,20 +1392,26 @@ async def get_chat_image(
             if md5_from_msg:
                 md5 = md5_from_msg
 
-    # md5 模式：优先从解密资源目录读取（更快）
+    cached_path: Optional[Path] = None
+    cached_data = b""
+    cached_media_type = "application/octet-stream"
+
+    # md5 模式：优先检查解密资源目录；如果微信目录里已经有更高质量版本，会在后面自动升级。
     if md5:
         decrypted_path = _try_find_decrypted_resource(account_dir, str(md5).lower())
         if decrypted_path:
             data = decrypted_path.read_bytes()
             media_type = _detect_image_media_type(data[:32])
             if media_type != "application/octet-stream" and _is_probably_valid_image(data, media_type):
-                return Response(content=data, media_type=media_type)
+                cached_path = decrypted_path
+                cached_data = data
+                cached_media_type = media_type
             # Corrupted cached file (e.g. wrong ext / partial data): remove and regenerate from source.
-            try:
-                if decrypted_path.suffix.lower() in {".jpg", ".jpeg", ".png", ".gif", ".webp"}:
+            elif decrypted_path.suffix.lower() in {".jpg", ".jpeg", ".png", ".gif", ".webp"}:
+                try:
                     decrypted_path.unlink()
-            except Exception:
-                pass
+                except Exception:
+                    pass
 
     # 回退：从微信数据目录实时定位并解密
     wxid_dir = _resolve_account_wxid_dir(account_dir)
@@ -1414,11 +1501,36 @@ async def get_chat_image(
                 break
 
     if not p:
+        if cached_path:
+            return _build_uncached_media_response(cached_data, cached_media_type)
         raise HTTPException(status_code=404, detail="Image not found.")
 
     candidates.extend(_iter_media_source_candidates(p))
     candidates = _order_media_candidates(candidates)
 
+    if cached_path:
+        try:
+            cached_key = str(cached_path.resolve())
+        except Exception:
+            cached_key = str(cached_path)
+
+        live_candidates: list[Path] = []
+        seen_live: set[str] = set()
+        for candidate in candidates:
+            try:
+                key = str(candidate.resolve())
+            except Exception:
+                key = str(candidate)
+            if key == cached_key or key in seen_live:
+                continue
+            seen_live.add(key)
+            live_candidates.append(candidate)
+
+        if _should_prefer_live_image_candidates(cached_path=cached_path, live_candidates=live_candidates):
+            candidates = [*live_candidates, cached_path]
+        else:
+            candidates = [cached_path, *live_candidates]
+
     logger.info(f"chat_image: md5={md5} file_id={file_id} candidates={len(candidates)} first={p}")
 
     data = b""
@@ -1443,19 +1555,14 @@ async def get_chat_image(
     # 仅在 md5 有效时缓存到 resource 目录；file_id 可能非常长，避免写入超长文件名
     if md5 and media_type.startswith("image/"):
         try:
-            out_md5 = str(md5).lower()
-            ext = _detect_image_extension(data)
-            out_path = _get_decrypted_resource_path(account_dir, out_md5, ext)
-            out_path.parent.mkdir(parents=True, exist_ok=True)
-            if not out_path.exists():
-                out_path.write_bytes(data)
+            _write_cached_chat_image(account_dir, str(md5), data)
         except Exception:
             pass
 
     logger.info(
         f"chat_image: md5={md5} file_id={file_id} chosen={chosen} media_type={media_type} bytes={len(data)}"
     )
-    return Response(content=data, media_type=media_type)
+    return _build_uncached_media_response(data, media_type)
 
 
 @router.get("/api/chat/media/emoji", summary="获取表情消息资源")
diff --git a/tests/test_chat_media_image_cache_upgrade.py b/tests/test_chat_media_image_cache_upgrade.py
