补充头像缓存同步与清理调试日志

utils/wechat/contact_manager.py

@@ -147,23 +147,25 @@ class ContactManager:
         except Exception as exc:
             self._logger.warning(f"保存头像缓存索引失败: {exc}")
 
-    def _delete_avatar_file_by_name(self, file_name: str) -> None:
+    def _delete_avatar_file_by_name(self, file_name: str) -> bool:
         """按文件名删除缓存头像，删除失败时只记日志不打断主流程。"""
         file_name = str(file_name or "").strip()
         if not file_name or not self._avatar_cache_dir:
-            return
+            return False
         target_path = self._avatar_cache_dir / file_name
         if not target_path.exists():
-            return
+            return False
         try:
             target_path.unlink()
+            return True
         except Exception as exc:
             self._logger.warning(f"删除旧头像缓存失败 file={target_path}: {exc}")
+            return False
 
-    def _cleanup_avatar_cache_files(self) -> None:
+    def _cleanup_avatar_cache_files(self) -> Dict[str, int]:
         """清理缓存目录里的孤儿头像文件与残留临时文件。"""
         if not self._avatar_cache_dir:
-            return
+            return {"orphan_deleted": 0, "tmp_deleted": 0}
 
         # 允许保留 manifest 自身，其余不在当前索引里的文件一律视为孤儿文件。
         referenced_files = {
@@ -172,6 +174,7 @@ class ContactManager:
             if str(meta.get("file_name") or "").strip()
         }
         manifest_name = self._avatar_manifest_path.name if self._avatar_manifest_path else ""
+        cleanup_stats = {"orphan_deleted": 0, "tmp_deleted": 0}
 
         for file_path in self._avatar_cache_dir.iterdir():
             if not file_path.is_file():
@@ -180,10 +183,13 @@ class ContactManager:
                 continue
             # `.tmp` 文件说明上次下载未完整落盘，直接清掉，避免长时间堆积。
             if file_path.suffix.lower() == ".tmp":
-                self._delete_avatar_file_by_name(file_path.name)
+                if self._delete_avatar_file_by_name(file_path.name):
+                    cleanup_stats["tmp_deleted"] += 1
                 continue
             if file_path.name not in referenced_files:
-                self._delete_avatar_file_by_name(file_path.name)
+                if self._delete_avatar_file_by_name(file_path.name):
+                    cleanup_stats["orphan_deleted"] += 1
+        return cleanup_stats
 
     def _guess_avatar_extension(self, avatar_url: str, content_type: str) -> str:
         """推断头像文件扩展名，尽量保留真实图片类型。"""
@@ -243,6 +249,16 @@ class ContactManager:
             return
 
         manifest_changed = False
+        # 统计字段用于打 debug 汇总日志，方便观察“初始化第一批头像”时到底发生了什么：
+        # 1. reuse_count 表示命中本地缓存、无需下载；
+        # 2. download_count 表示本轮真正新增或重拉的头像数量；
+        # 3. replaced_count 表示头像 URL 变更导致发生了“新旧替换”；
+        # 4. removed_contact_count / removed_file_count 表示联系人消失后同步移除了多少记录和文件。
+        reuse_count = 0
+        download_count = 0
+        replaced_count = 0
+        removed_contact_count = 0
+        removed_file_count = 0
         with self._avatar_cache_lock:
             for wxid, avatar_url in self._head_images.items():
                 remote_url = str(avatar_url or "").strip()
@@ -253,31 +269,55 @@ class ContactManager:
                 cached_path = self.get_cached_head_image_path(wxid)
                 # 只有“URL 变了”或“本地文件丢了”才重新下载，避免刷新通讯录时重复打远端。
                 if manifest_item.get("remote_url") == remote_url and cached_path:
+                    reuse_count += 1
                     continue
                 downloaded_path = self._download_avatar_to_cache(wxid, remote_url)
                 if not downloaded_path:
+                    self._logger.debug(f"头像缓存同步跳过 wxid={wxid} reason=download_failed")
                     continue
                 self._avatar_manifest[wxid] = {
                     "file_name": Path(downloaded_path).name,
                     "remote_url": remote_url,
                 }
+                download_count += 1
                 # 同一联系人头像地址变化后，旧文件已经失去引用，这里立刻删掉旧版本。
                 if old_file_name and old_file_name != Path(downloaded_path).name:
-                    self._delete_avatar_file_by_name(old_file_name)
+                    if self._delete_avatar_file_by_name(old_file_name):
+                        removed_file_count += 1
+                    replaced_count += 1
+                    self._logger.debug(
+                        f"头像缓存已替换 wxid={wxid} old={old_file_name} new={Path(downloaded_path).name}"
+                    )
+                else:
+                    self._logger.debug(f"头像缓存已下载 wxid={wxid} file={Path(downloaded_path).name}")
                 manifest_changed = True
 
             # 把已经不在通讯录中的头像记录清理掉，避免 manifest 无限增长。
             removed_wxids = [wxid for wxid in self._avatar_manifest.keys() if wxid not in self._head_images]
             for wxid in removed_wxids:
                 removed_meta = self._avatar_manifest.pop(wxid, None) or {}
-                self._delete_avatar_file_by_name(str(removed_meta.get("file_name") or "").strip())
+                removed_contact_count += 1
+                if self._delete_avatar_file_by_name(str(removed_meta.get("file_name") or "").strip()):
+                    removed_file_count += 1
                 manifest_changed = True
 
             if manifest_changed:
                 self._save_avatar_manifest()
             # 无论本轮 manifest 是否有变化，都顺手做一次目录对账，
             # 保证历史异常中断留下的孤儿文件也能逐步被回收。
-            self._cleanup_avatar_cache_files()
+            cleanup_stats = self._cleanup_avatar_cache_files()
+            self._logger.debug(
+                "头像缓存同步完成 "
+                f"total_head_images={len(self._head_images)} "
+                f"manifest_entries={len(self._avatar_manifest)} "
+                f"reuse={reuse_count} "
+                f"downloaded={download_count} "
+                f"replaced={replaced_count} "
+                f"removed_contacts={removed_contact_count} "
+                f"removed_files={removed_file_count} "
+                f"orphan_deleted={cleanup_stats.get('orphan_deleted', 0)} "
+                f"tmp_deleted={cleanup_stats.get('tmp_deleted', 0)}"
+            )
 
     def get_cached_head_image_path(self, wxid: str) -> str:
         """返回头像缓存本地路径，若缓存不存在则返回空字符串。"""
@@ -297,8 +337,10 @@ class ContactManager:
         # 如果本地已有缓存，且当前头像 URL 没变，就直接复用；
         # 如果 URL 已变化，则继续往下重拉新头像，避免页面一直展示旧图。
         if cached_path and (not remote_url or manifest_item.get("remote_url") == remote_url):
+            self._logger.debug(f"头像缓存命中 wxid={wxid} file={Path(cached_path).name}")
             return cached_path
         if not remote_url:
+            self._logger.debug(f"头像缓存缺失 wxid={wxid} reason=no_remote_url")
             return ""
 
         with self._avatar_cache_lock:
@@ -307,19 +349,32 @@ class ContactManager:
             old_file_name = str(manifest_item.get("file_name") or "").strip()
             cached_path = self.get_cached_head_image_path(wxid)
             if cached_path and manifest_item.get("remote_url") == remote_url:
+                self._logger.debug(f"头像缓存命中 wxid={wxid} file={Path(cached_path).name}")
                 return cached_path
             downloaded_path = self._download_avatar_to_cache(wxid, remote_url)
             if not downloaded_path:
+                self._logger.debug(f"头像缓存补下载失败 wxid={wxid}")
                 return ""
             self._avatar_manifest[wxid] = {
                 "file_name": Path(downloaded_path).name,
                 "remote_url": remote_url,
             }
             # 单头像补下载时同样清掉旧版本，避免访问链路把目录越堆越大。
+            removed_file_count = 0
             if old_file_name and old_file_name != Path(downloaded_path).name:
-                self._delete_avatar_file_by_name(old_file_name)
+                if self._delete_avatar_file_by_name(old_file_name):
+                    removed_file_count += 1
             self._save_avatar_manifest()
-            self._cleanup_avatar_cache_files()
+            cleanup_stats = self._cleanup_avatar_cache_files()
+            self._logger.debug(
+                "头像缓存补下载完成 "
+                f"wxid={wxid} "
+                f"file={Path(downloaded_path).name} "
+                f"replaced={'Y' if bool(old_file_name and old_file_name != Path(downloaded_path).name) else 'N'} "
+                f"removed_files={removed_file_count} "
+                f"orphan_deleted={cleanup_stats.get('orphan_deleted', 0)} "
+                f"tmp_deleted={cleanup_stats.get('tmp_deleted', 0)}"
+            )
             return downloaded_path
 
     def get_head_image_version(self, wxid: str) -> str: