first commit

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "liveServer.settings.port": 5502
+}

api.md

@@ -0,0 +1,226 @@
+# TuneHub API 文档
+
+TuneHub 是一个统一的音乐信息解析服务。它打破了不同音乐平台之间的壁垒，提供了一套标准化的 API 接口。
+
+**Base URL:** `https://music-dl.sayqz.com`
+**Version:** 1.0.0
+
+---
+
+## 核心 API
+
+### 1. 获取歌曲基本信息
+
+获取歌曲的名称、歌手、专辑等基本元数据信息。
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识 (例如: `netease`, `kuwo`, `qq`).
+    *   `id`: `string` - **必需**. 歌曲 ID.
+    *   `type`: `string` - **必需**. 固定为 `info`.
+*   **Response Example (200 OK):**
+    ```json
+    {
+      "code": 200,
+      "message": "success",
+      "data": {
+        "name": "歌曲名称",
+        "artist": "歌手名称",
+        "album": "专辑名称",
+        "url": "https://music-dl.sayqz.com/api/?source=netease&id=123456&type=url",
+        "pic": "https://music-dl.sayqz.com/api/?source=netease&id=123456&type=pic",
+        "lrc": "https://music-dl.sayqz.com/api/?source=netease&id=123456&type=lrc"
+      },
+      "timestamp": "2025-11-23T12:00:00.000+08:00"
+    }
+    ```
+
+### 2. 获取音乐文件链接
+
+获取音乐文件链接。成功时返回 302 Redirect 到实际的音乐文件 URL。
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `id`: `string` - **必需**. 歌曲 ID.
+    *   `type`: `string` - **必需**. 固定为 `url`.
+    *   `br`: `string` - *可选*. 音质 (默认: `320k`). 可选值: `128k`, `320k`, `flac`, `flac24bit`.
+
+### 3. 获取专辑封面
+
+获取歌曲的专辑封面图片。成功时返回 302 Redirect 到图片 URL。
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `id`: `string` - **必需**. 歌曲 ID.
+    *   `type`: `string` - **必需**. 固定为 `pic`.
+
+### 4. 获取歌词
+
+获取LRC格式的歌词。
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `id`: `string` - **必需**. 歌曲 ID.
+    *   `type`: `string` - **必需**. 固定为 `lrc`.
+*   **Response Example (200 OK, text/plain):**
+    ```
+    [00:00.00]歌词第一行
+    [00:05.50]歌词第二行
+    ```
+
+### 5. 搜索歌曲
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `type`: `string` - **必需**. 固定为 `search`.
+    *   `keyword`: `string` - **必需**. 搜索关键词.
+    *   `limit`: `integer` - *可选*. 返回数量 (默认: 20).
+*   **Response Example (200 OK):**
+    ```json
+    {
+      "code": 200,
+      "message": "success",
+      "data": {
+        "keyword": "周杰伦",
+        "total": 10,
+        "results": [
+          {
+            "id": "123456",
+            "name": "歌曲名称",
+            "artist": "周杰伦",
+            "album": "专辑名称",
+            "url": "https://music-dl.sayqz.com/api/?...",
+            "platform": "netease"
+          }
+        ]
+      }
+    }
+    ```
+
+### 6. 聚合搜索
+
+一次性并发请求所有启用的平台，并对结果进行智能混合排列。
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `type`: `string` - **必需**. 固定为 `aggregateSearch`.
+    *   `keyword`: `string` - **必需**. 搜索关键词.
+*   **Response Example (200 OK):**
+    ```json
+    {
+      "code": 200,
+      "message": "success",
+      "data": {
+        "keyword": "周杰伦",
+        "results": [
+          {
+            "id": "123456",
+            "name": "歌曲名称",
+            "artist": "周杰伦",
+            "platform": "netease"
+          },
+          {
+            "id": "789012",
+            "name": "另一首歌",
+            "artist": "周杰伦",
+            "platform": "kuwo"
+          }
+        ]
+      }
+    }
+    ```
+
+### 7. 获取歌单详情
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `id`: `string` - **必需**. 歌单 ID.
+    *   `type`: `string` - **必需**. 固定为 `playlist`.
+
+### 8. 获取排行榜列表
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `type`: `string` - **必需**. 固定为 `toplists`.
+
+### 9. 获取排行榜歌曲
+
+*   **Method:** `GET`
+*   **Endpoint:** `/api/`
+*   **Query Parameters:**
+    *   `source`: `string` - **必需**. 平台标识.
+    *   `id`: `string` - **必需**. 排行榜 ID.
+    *   `type`: `string` - **必需**. 固定为 `toplist`.
+
+---
+
+## 系统 API
+
+### 10. 系统状态
+
+*   **Method:** `GET`
+*   **Endpoint:** `/status`
+
+### 11. 健康检查
+
+*   **Method:** `GET`
+*   **Endpoint:** `/health`
+
+---
+
+## 统计 API
+
+### 12. 获取统计数据
+
+*   **Method:** `GET`
+*   **Endpoint:** `/stats`
+*   **Query Parameters:**
+    *   `period`: `string` - *可选*. 时间段 (默认: `today`).
+    *   `groupBy`: `string` - *可选*. 分组依据 (默认: `platform`).
+
+### 13. 获取统计摘要
+
+*   **Method:** `GET`
+*   **Endpoint:** `/stats/summary`
+
+### 14. 平台统计概览
+
+*   **Method:** `GET`
+*   **Endpoint:** `/stats/platforms`
+*   **Query Parameters:**
+    *   `period`: `string` - *可选*. 时间段 (默认: `today`).
+
+### 15. QPS 统计
+
+*   **Method:** `GET`
+*   **Endpoint:** `/stats/qps`
+*   **Query Parameters:**
+    *   `period`: `string` - *可选*. 时间段 (默认: `today`).
+
+### 16. 趋势数据
+
+*   **Method:** `GET`
+*   **Endpoint:** `/stats/trends`
+*   **Query Parameters:**
+    *   `period`: `string` - *可选*. 时间段 (默认: `week`).
+
+### 17. 请求类型统计
+
+*   **Method:** `GET`
+*   **Endpoint:** `/stats/types`
+*   **Query Parameters:**
+    *   `period`: `string` - *可选*. 时间段 (默认: `today`).