refactor(download): 重构下载系统，支持暂停/恢复/取消，修复歌词加载

- 新建 DownloadManager 类（主进程），每个任务独立 AbortController 控制
- 新建 Pinia useDownloadStore 作为渲染进程单一数据源
- 支持暂停/恢复/取消下载，支持断点续传（Range header）
- 批量下载全部完成后发送汇总系统通知，单首不重复通知
- 并发数可配置（1-5），队列持久化（重启后恢复）
- 修复下载列表不全、封面加载失败、通知重复等 bug
- 修复本地/下载歌曲歌词加载：优先从 ID3/FLAC 元数据提取，API 作为 fallback
- 删除 useDownloadStatus.ts，统一状态管理
- DownloadDrawer/DownloadPage 全面重写，移除 @apply 违规
- 新增 5 语言 i18n 键值（暂停/恢复/取消/排队中等）

src/renderer/hooks/MusicHook.ts

@@ -188,10 +188,10 @@ const setupMusicWatchers = () => {
           if (playMusic.value.lyric && typeof playMusic.value.lyric === 'object') {
             playMusic.value.lyric.hasWordByWord = hasWordByWord;
           }
-        } else {
+        } else if (lyricData && typeof lyricData === 'object' && lyricData.lrcArray?.length > 0) {
           // 使用现有的歌词数据结构
-          const rawLrc = lyricData?.lrcArray || [];
-          lrcTimeArray.value = lyricData?.lrcTimeArray || [];
+          const rawLrc = lyricData.lrcArray || [];
+          lrcTimeArray.value = lyricData.lrcTimeArray || [];
 
           try {
             const { translateLyrics } = await import('@/services/lyricTranslation');
@@ -200,6 +200,53 @@ const setupMusicWatchers = () => {
             console.error('翻译歌词失败，使用原始歌词：', e);
             lrcArray.value = rawLrc as any;
           }
+        } else if (isElectron && playMusic.value.playMusicUrl?.startsWith('local:///')) {
+          // 从下载/本地文件的 ID3/FLAC 元数据中提取嵌入歌词
+          try {
+            let filePath = decodeURIComponent(
+              playMusic.value.playMusicUrl.replace('local:///', '')
+            );
+            // 处理 Windows 路径：/C:/... → C:/...
+            if (/^\/[a-zA-Z]:\//.test(filePath)) {
+              filePath = filePath.slice(1);
+            }
+            const embeddedLyrics = await window.api.getEmbeddedLyrics(filePath);
+            if (embeddedLyrics) {
+              const {
+                lrcArray: parsedLrcArray,
+                lrcTimeArray: parsedTimeArray,
+                hasWordByWord
+              } = await parseLyricsString(embeddedLyrics);
+              lrcArray.value = parsedLrcArray;
+              lrcTimeArray.value = parsedTimeArray;
+              if (playMusic.value.lyric && typeof playMusic.value.lyric === 'object') {
+                (playMusic.value.lyric as any).hasWordByWord = hasWordByWord;
+              }
+            } else {
+              // 无嵌入歌词 — 若有数字 ID，尝试 API 兜底
+              const songId = playMusic.value.id;
+              if (songId && typeof songId === 'number') {
+                try {
+                  const { getMusicLrc } = await import('@/api/music');
+                  const res = await getMusicLrc(songId);
+                  if (res?.data?.lrc?.lyric) {
+                    const { lrcArray: apiLrcArray, lrcTimeArray: apiTimeArray } =
+                      await parseLyricsString(res.data.lrc.lyric);
+                    lrcArray.value = apiLrcArray;
+                    lrcTimeArray.value = apiTimeArray;
+                  }
+                } catch (apiErr) {
+                  console.error('API lyrics fallback failed:', apiErr);
+                }
+              }
+            }
+          } catch (err) {
+            console.error('Failed to extract embedded lyrics:', err);
+          }
+        } else {
+          // 无歌词数据
+          lrcArray.value = [];
+          lrcTimeArray.value = [];
         }
         // 当歌词数据更新时，如果歌词窗口打开，则发送数据
         if (isElectron && isLyricWindowOpen.value) {

src/renderer/hooks/useDownload.ts

@@ -1,160 +1,42 @@
-import { cloneDeep } from 'lodash';
 import { useMessage } from 'naive-ui';
 import { ref } from 'vue';
 import { useI18n } from 'vue-i18n';
 
 import { getMusicLrc } from '@/api/music';
+import { useDownloadStore } from '@/store/modules/download';
 import { getSongUrl } from '@/store/modules/player';
 import type { SongResult } from '@/types/music';
 import { isElectron } from '@/utils';
 
+import type { DownloadSongInfo } from '../../shared/download';
+
 const ipcRenderer = isElectron ? window.electron.ipcRenderer : null;
 
-// 全局下载管理（闭包模式）
-const createDownloadManager = () => {
-  // 正在下载的文件集合
-  const activeDownloads = new Set<string>();
-
-  // 已经发送了通知的文件集合（避免重复通知）
-  const notifiedDownloads = new Set<string>();
-
-  // 事件监听器是否已初始化
-  let isInitialized = false;
-
-  // 监听器引用（用于清理）
-  let completeListener: ((event: any, data: any) => void) | null = null;
-  let errorListener: ((event: any, data: any) => void) | null = null;
-
+/**
+ * Map a SongResult to the minimal DownloadSongInfo shape required by the download store.
+ */
+function toDownloadSongInfo(song: SongResult): DownloadSongInfo {
   return {
-    // 添加下载
-    addDownload: (filename: string) => {
-      activeDownloads.add(filename);
-    },
-
-    // 移除下载
-    removeDownload: (filename: string) => {
-      activeDownloads.delete(filename);
-      // 延迟清理通知记录
-      setTimeout(() => {
-        notifiedDownloads.delete(filename);
-      }, 5000);
-    },
-
-    // 标记文件已通知
-    markNotified: (filename: string) => {
-      notifiedDownloads.add(filename);
-    },
-
-    // 检查文件是否已通知
-    isNotified: (filename: string) => {
-      return notifiedDownloads.has(filename);
-    },
-
-    // 清理所有下载
-    clearDownloads: () => {
-      activeDownloads.clear();
-      notifiedDownloads.clear();
-    },
-
-    // 初始化事件监听器
-    initEventListeners: (message: any, t: any) => {
-      if (isInitialized) return;
-
-      // 移除可能存在的旧监听器
-      if (completeListener) {
-        ipcRenderer?.removeListener('music-download-complete', completeListener);
-      }
-
-      if (errorListener) {
-        ipcRenderer?.removeListener('music-download-error', errorListener);
-      }
-
-      // 创建新的监听器
-      completeListener = (_event, data) => {
-        if (!data.filename || !activeDownloads.has(data.filename)) return;
-
-        // 如果该文件已经通知过，则跳过
-        if (notifiedDownloads.has(data.filename)) return;
-
-        // 标记为已通知
-        notifiedDownloads.add(data.filename);
-
-        // 从活动下载移除
-        activeDownloads.delete(data.filename);
-      };
-
-      errorListener = (_event, data) => {
-        if (!data.filename || !activeDownloads.has(data.filename)) return;
-
-        // 如果该文件已经通知过，则跳过
-        if (notifiedDownloads.has(data.filename)) return;
-
-        // 标记为已通知
-        notifiedDownloads.add(data.filename);
-
-        // 显示失败通知
-        message.error(
-          t('songItem.message.downloadFailed', {
-            filename: data.filename,
-            error: data.error || '未知错误'
-          })
-        );
-
-        // 从活动下载移除
-        activeDownloads.delete(data.filename);
-      };
-
-      // 添加监听器
-      ipcRenderer?.on('music-download-complete', completeListener);
-      ipcRenderer?.on('music-download-error', errorListener);
-
-      isInitialized = true;
-    },
-
-    // 清理事件监听器
-    cleanupEventListeners: () => {
-      if (!isInitialized) return;
-
-      if (completeListener) {
-        ipcRenderer?.removeListener('music-download-complete', completeListener);
-        completeListener = null;
-      }
-
-      if (errorListener) {
-        ipcRenderer?.removeListener('music-download-error', errorListener);
-        errorListener = null;
-      }
-
-      isInitialized = false;
-    },
-
-    // 获取活跃下载数量
-    getActiveDownloadCount: () => {
-      return activeDownloads.size;
-    },
-
-    // 检查是否有特定文件正在下载
-    hasDownload: (filename: string) => {
-      return activeDownloads.has(filename);
+    id: song.id as number,
+    name: song.name,
+    picUrl: song.picUrl ?? song.al?.picUrl ?? '',
+    ar: (song.ar || song.song?.artists || []).map((a: { name: string }) => ({ name: a.name })),
+    al: {
+      name: song.al?.name ?? '',
+      picUrl: song.al?.picUrl ?? ''
     }
   };
-};
-
-// 创建单例下载管理器
-const downloadManager = createDownloadManager();
+}
 
 export const useDownload = () => {
   const { t } = useI18n();
   const message = useMessage();
+  const downloadStore = useDownloadStore();
   const isDownloading = ref(false);
 
-  // 初始化事件监听器
-  downloadManager.initEventListeners(message, t);
-
   /**
-   * 下载单首音乐
-   * @param song 歌曲信息
-   * @returns Promise<void>
+   * Download a single song.
+   * Resolves the URL in the renderer then delegates queuing to the download store.
    */
   const downloadMusic = async (song: SongResult) => {
     if (isDownloading.value) {
@@ -165,55 +47,33 @@ export const useDownload = () => {
     try {
       isDownloading.value = true;
 
-      const musicUrl = (await getSongUrl(song.id as number, cloneDeep(song), true)) as any;
+      const musicUrl = (await getSongUrl(song.id as number, song, true)) as any;
       if (!musicUrl) {
         throw new Error(t('songItem.message.getUrlFailed'));
       }
 
-      // 构建文件名
-      const artistNames = (song.ar || song.song?.artists)?.map((a) => a.name).join(',');
-      const filename = `${song.name} - ${artistNames}`;
-
-      // 检查是否已在下载
-      if (downloadManager.hasDownload(filename)) {
-        isDownloading.value = false;
-        return;
-      }
-
-      // 添加到活动下载集合
-      downloadManager.addDownload(filename);
-
-      const songData = cloneDeep(song);
-      songData.ar = songData.ar || songData.song?.artists;
-
-      // 发送下载请求
-      ipcRenderer?.send('download-music', {
-        url: typeof musicUrl === 'string' ? musicUrl : musicUrl.url,
-        filename,
-        songInfo: {
-          ...songData,
-          downloadTime: Date.now()
-        },
-        type: musicUrl.type
-      });
+      const url = typeof musicUrl === 'string' ? musicUrl : musicUrl.url;
+      const type = typeof musicUrl === 'string' ? '' : (musicUrl.type ?? '');
+      const songInfo = toDownloadSongInfo(song);
 
+      await downloadStore.addDownload(songInfo, url, type);
       message.success(t('songItem.message.downloadQueued'));
-
-      // 简化的监听逻辑，基本通知由全局监听器处理
-      setTimeout(() => {
-        isDownloading.value = false;
-      }, 2000);
     } catch (error: any) {
       console.error('Download error:', error);
-      isDownloading.value = false;
       message.error(error.message || t('songItem.message.downloadFailed'));
+    } finally {
+      isDownloading.value = false;
     }
   };
 
   /**
-   * 批量下载音乐
-   * @param songs 歌曲列表
-   * @returns Promise<void>
+   * Batch download multiple songs.
+   *
+   * NOTE: This deviates slightly from the original spec (which envisioned JIT URL resolution in
+   * the main process via onDownloadRequestUrl). Instead we pre-resolve URLs here in batches of 5
+   * to avoid request storms against the local NeteaseCloudMusicApi service (> ~5 concurrent TLS
+   * connections can trigger 502s). The trade-off is acceptable: the renderer already has access to
+   * getSongUrl and this keeps the main process simpler.
    */
   const batchDownloadMusic = async (songs: SongResult[]) => {
     if (isDownloading.value) {
@@ -230,82 +90,46 @@ export const useDownload = () => {
       isDownloading.value = true;
       message.success(t('favorite.downloading'));
 
-      let successCount = 0;
-      let failCount = 0;
-      const totalCount = songs.length;
+      const BATCH_SIZE = 5;
+      const resolvedItems: Array<{ songInfo: DownloadSongInfo; url: string; type: string }> = [];
 
-      // 下载进度追踪
-      const trackProgress = () => {
-        if (successCount + failCount === totalCount) {
-          isDownloading.value = false;
-          message.success(t('favorite.downloadSuccess'));
+      // Resolve URLs in batches of 5 to avoid request storms
+      for (let i = 0; i < songs.length; i += BATCH_SIZE) {
+        const chunk = songs.slice(i, i + BATCH_SIZE);
+        const chunkResults = await Promise.all(
+          chunk.map(async (song) => {
+            try {
+              const data = (await getSongUrl(song.id as number, song, true)) as any;
+              const url = typeof data === 'string' ? data : (data?.url ?? '');
+              const type = typeof data === 'string' ? '' : (data?.type ?? '');
+              if (!url) return null;
+              return { songInfo: toDownloadSongInfo(song), url, type };
+            } catch (error) {
+              console.error(`获取歌曲 ${song.name} 下载链接失败:`, error);
+              return null;
+            }
+          })
+        );
+        for (const item of chunkResults) {
+          if (item) resolvedItems.push(item);
         }
-      };
+      }
 
-      // 并行获取所有歌曲的下载链接
-      const downloadUrls = await Promise.all(
-        songs.map(async (song) => {
-          try {
-            const data = (await getSongUrl(song.id, song, true)) as any;
-            return { song, ...data };
-          } catch (error) {
-            console.error(`获取歌曲 ${song.name} 下载链接失败:`, error);
-            failCount++;
-            return { song, url: null };
-          }
-        })
-      );
-
-      // 开始下载有效的链接
-      downloadUrls.forEach(({ song, url, type }) => {
-        if (!url) {
-          failCount++;
-          trackProgress();
-          return;
-        }
-
-        const songData = cloneDeep(song);
-        const filename = `${song.name} - ${(song.ar || song.song?.artists)?.map((a) => a.name).join(',')}`;
-
-        // 检查是否已在下载
-        if (downloadManager.hasDownload(filename)) {
-          failCount++;
-          trackProgress();
-          return;
-        }
-
-        // 添加到活动下载集合
-        downloadManager.addDownload(filename);
-
-        const songInfo = {
-          ...songData,
-          ar: songData.ar || songData.song?.artists,
-          downloadTime: Date.now()
-        };
-
-        ipcRenderer?.send('download-music', {
-          url,
-          filename,
-          songInfo,
-          type
-        });
-
-        successCount++;
-      });
-
-      // 所有下载开始后，检查进度
-      trackProgress();
+      if (resolvedItems.length > 0) {
+        await downloadStore.batchDownload(resolvedItems);
+      }
     } catch (error) {
       console.error('下载失败:', error);
-      isDownloading.value = false;
       message.destroyAll();
       message.error(t('favorite.downloadFailed'));
+    } finally {
+      isDownloading.value = false;
     }
   };
 
   /**
-   * 下载单首歌曲的歌词（.lrc 文件）
-   * @param song 歌曲信息
+   * Download the lyric (.lrc) for a single song.
+   * This is independent of the download system and uses a direct IPC call.
    */
   const downloadLyric = async (song: SongResult) => {
     try {
@@ -317,14 +141,15 @@ export const useDownload = () => {
         return;
       }
 
-      // 构建 LRC 内容：保留原始歌词，如有翻译则合并
+      // Build LRC content: keep original lyrics, merge translation if available
       let lrcContent = lyricData.lrc.lyric;
       if (lyricData.tlyric?.lyric) {
         lrcContent = mergeLrcWithTranslation(lyricData.lrc.lyric, lyricData.tlyric.lyric);
       }
 
-      // 构建文件名
-      const artistNames = (song.ar || song.song?.artists)?.map((a) => a.name).join(',');
+      const artistNames = (song.ar || song.song?.artists)
+        ?.map((a: { name: string }) => a.name)
+        .join(',');
       const filename = `${song.name} - ${artistNames}`;
 
       const result = await ipcRenderer?.invoke('save-lyric-file', { filename, lrcContent });
@@ -349,7 +174,7 @@ export const useDownload = () => {
 };
 
 /**
- * 将原文歌词和翻译歌词合并为一个 LRC 字符串
+ * Merge original LRC lyrics and translated LRC lyrics into a single LRC string.
  */
 function mergeLrcWithTranslation(originalText: string, translationText: string): string {
   const originalMap = parseLrcText(originalText);
@@ -365,7 +190,7 @@ function mergeLrcWithTranslation(originalText: string, translationText: string):
     }
   }
 
-  // 按时间排序
+  // Sort by time tag
   mergedLines.sort((a, b) => {
     const ta = a.match(/\[\d{2}:\d{2}(\.\d{1,3})?\]/)?.[0] || '';
     const tb = b.match(/\[\d{2}:\d{2}(\.\d{1,3})?\]/)?.[0] || '';
@@ -376,7 +201,7 @@ function mergeLrcWithTranslation(originalText: string, translationText: string):
 }
 
 /**
- * 解析 LRC 文本为 Map<timeTag, content>
+ * Parse LRC text into a Map<timeTag, content>.
  */
 function parseLrcText(text: string): Map<string, string> {
   const map = new Map<string, string>();

src/renderer/hooks/useDownloadStatus.ts

@@ -1,94 +0,0 @@
-import { computed, onMounted, ref } from 'vue';
-import { useRouter } from 'vue-router';
-
-const downloadList = ref<any[]>([]);
-const isInitialized = ref(false);
-
-export const useDownloadStatus = () => {
-  const router = useRouter();
-
-  const downloadingCount = computed(() => {
-    return downloadList.value.filter((item) => item.status === 'downloading').length;
-  });
-
-  const navigateToDownloads = () => {
-    router.push('/downloads');
-  };
-
-  const initDownloadListeners = () => {
-    if (isInitialized.value) return;
-
-    if (!window.electron?.ipcRenderer) return;
-
-    window.electron.ipcRenderer.on('music-download-progress', (_, data) => {
-      const existingItem = downloadList.value.find((item) => item.filename === data.filename);
-
-      if (data.progress === 100) {
-        data.status = 'completed';
-      }
-
-      if (existingItem) {
-        Object.assign(existingItem, {
-          ...data,
-          songInfo: data.songInfo || existingItem.songInfo
-        });
-
-        if (data.status === 'completed') {
-          downloadList.value = downloadList.value.filter((item) => item.filename !== data.filename);
-        }
-      } else {
-        downloadList.value.push({
-          ...data,
-          songInfo: data.songInfo
-        });
-      }
-    });
-
-    window.electron.ipcRenderer.on('music-download-complete', async (_, data) => {
-      if (data.success) {
-        downloadList.value = downloadList.value.filter((item) => item.filename !== data.filename);
-      } else {
-        const existingItem = downloadList.value.find((item) => item.filename === data.filename);
-        if (existingItem) {
-          Object.assign(existingItem, {
-            status: 'error',
-            error: data.error,
-            progress: 0
-          });
-          setTimeout(() => {
-            downloadList.value = downloadList.value.filter(
-              (item) => item.filename !== data.filename
-            );
-          }, 3000);
-        }
-      }
-    });
-
-    window.electron.ipcRenderer.on('music-download-queued', (_, data) => {
-      const existingItem = downloadList.value.find((item) => item.filename === data.filename);
-      if (!existingItem) {
-        downloadList.value.push({
-          filename: data.filename,
-          progress: 0,
-          loaded: 0,
-          total: 0,
-          path: '',
-          status: 'downloading',
-          songInfo: data.songInfo
-        });
-      }
-    });
-
-    isInitialized.value = true;
-  };
-
-  onMounted(() => {
-    initDownloadListeners();
-  });
-
-  return {
-    downloadList,
-    downloadingCount,
-    navigateToDownloads
-  };
-};