From f6db3e76e938ce94843a7c53a011940858a648cf Mon Sep 17 00:00:00 2001
From: floatwoozy <72070458+floatwoozy@users.noreply.github.com>
Date: Thu, 25 Jun 2026 03:11:11 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20listen=5Fdata=5Fso?=
 =?UTF-8?q?ng=5Fplay=5Frank=20=E6=AD=8C=E6=9B=B2=E6=92=AD=E6=94=BE?=
 =?UTF-8?q?=E6=8E=92=E8=A1=8C=E6=8E=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 /api/content/activity/listen/data/song/play/rank，返回某周/月
听歌排行（每首带 playCount），默认 Top20、不足则返回全部。与已有的
listen_data_today_song（今日）同族，补全「带次数的历史周/月榜」。

- module/listen_data_song_play_rank.js：type(week|month) + endTime 参数
- interface.d.ts：补类型声明
- public/docs/home.md：补接口文档
---
 interface.d.ts                       |  7 +++++++
 module/listen_data_song_play_rank.js | 12 ++++++++++++
 public/docs/home.md                  | 17 +++++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 module/listen_data_song_play_rank.js

diff --git a/interface.d.ts b/interface.d.ts
index 071338b..ad4cea6 100644
--- a/interface.d.ts
+++ b/interface.d.ts
@@ -2049,6 +2049,13 @@ export function listen_data_report(
   } & RequestBaseConfig,
 ): Promise<Response>
 
+export function listen_data_song_play_rank(
+  params: {
+    type?: string
+    endTime?: string | number
+  } & RequestBaseConfig,
+): Promise<Response>
+
 export function listen_data_today_song(
   params: RequestBaseConfig,
 ): Promise<Response>
diff --git a/module/listen_data_song_play_rank.js b/module/listen_data_song_play_rank.js
new file mode 100644
index 0000000..0e7940e
--- /dev/null
+++ b/module/listen_data_song_play_rank.js
@@ -0,0 +1,12 @@
+// 听歌足迹 - 歌曲播放排行 (Top20)
+const createOption = require('../util/option.js')
+module.exports = (query, request) => {
+  return request(
+    `/api/content/activity/listen/data/song/play/rank`,
+    {
+      type: query.type || 'month', //周 week 月 month
+      endTime: query.endTime, // 不填就是本周/月的
+    },
+    createOption(query),
+  )
+}
diff --git a/public/docs/home.md b/public/docs/home.md
index 5d1f87a..d88bff7 100644
--- a/public/docs/home.md
+++ b/public/docs/home.md
@@ -4810,6 +4810,23 @@ bitrate = Math.floor(br / 1000)
 
 **接口地址 :** `/listen/data/today/song`
 
+### 听歌足迹 - 歌曲播放排行
+
+说明 : 登录后调用此接口, 获取歌曲播放排行, 返回每首歌的播放次数 (playCount); 默认返回前 20 名 (Top20), 不足则返回全部
+
+**必选参数 :**
+
+`type`: 维度类型 周 week 月 month
+
+**可选参数 :**
+
+`endTime` : 周: 每周周六 0 点的时间戳 月: 每月最后一天 0 点的时间戳
+不填就是本周/月的
+
+**接口地址 :** `/listen/data/song/play/rank`
+
+**调用例子 :** `/listen/data/song/play/rank?type=month`
+
 ### 听歌足迹 - 总收听时长
 
 说明 : 登录后调用此接口, 获取总收听时长; 相关接口可能需要 vip 权限