diff --git a/docs/RELAY_PLAY_STATE_INTEGRATION.md b/docs/RELAY_PLAY_STATE_INTEGRATION.md new file mode 100644 index 0000000..7c342a7 --- /dev/null +++ b/docs/RELAY_PLAY_STATE_INTEGRATION.md @@ -0,0 +1,159 @@ +# relay_play_state_submit 集成说明 + +## 修改内容 + +### 1. 新增 API 接口模块 + +**文件**: `module/relay_play_state_submit.js` + +**功能**: 提交歌曲播放状态,支持会话追踪和播放模式记录 + +**接口地址**: `/api/relay/play/state/submit` + +**参数说明**: +- `id` (必填): 歌曲 ID +- `sessionId` (必填): 播放会话 ID(12 位大写字母和数字) +- `progress` (可选): 播放进度(秒),默认 0 +- `playMode` (可选): 播放模式,默认 `list_loop` +- `type` (可选): 资源类型,默认 `song` + +**参数校验**: +```javascript +if (!id || !sessionId) { + return Promise.reject({ + status: 400, + body: { + code: 400, + msg: '缺少必要参数:id, sessionId', + }, + }) +} +``` + +### 2. 更新 API 文档 + +**文件**: `public/docs/home.md` + +在文档末尾添加了接口说明,包括: +- 接口功能说明 +- 参数列表 +- 调用示例 + +### 3. 集成到自动任务脚本 + +**文件**: `auto_tasks_enhanced.js` + +**修改内容**: + +1. **导入接口** (Line 32): +```javascript +const { + // ... 其他接口 + relay_play_state_submit, + // ... 其他接口 +} = require('@neteasecloudmusicapienhanced/api') +``` + +2. **组合使用两个接口** (Lines 447-483): +```javascript +// 2. 上传听歌记录(组合使用两个接口) +console.log(' [2] 上传播放状态...') +try { + // 生成 sessionId(12 位大写字母和数字) + const sessionId = Math.random().toString(36).substring(2, 8).toUpperCase() + + Math.random().toString(36).substring(2, 8).toUpperCase() + + // 2.1 提交播放开始状态(relay_play_state_submit) + const relayResult = await relay_play_state_submit({ + cookie, + id: song.id, + sessionId: sessionId, + progress: 0, + playMode: 'list_loop' + }) + if (relayResult.body.code === 200) { + console.log(' ✓ 播放状态已提交') + } + + await sleep(1000) + + // 2.2 上传完整听歌记录(scrobble) + const playTime = Math.floor(song.dt / 1000) + const scrobbleResult = await scrobble({ + cookie, + id: song.id, + sourceid: playlistId, + time: playTime + }) + if (scrobbleResult.body.code === 200) { + const timeStr = (playTime / 60).toFixed(2) + console.log(` ✓ 听歌记录已上传 (${timeStr}分钟)`) + successCount++ + } +} catch (e) { + console.log(` 上传失败:${e.message}`) +} +``` + +## 工作流程 + +完整的 VIP 音乐任务播放流程: + +``` +1. 收藏歌曲 (song_like) + ↓ +2. 提交播放状态 (relay_play_state_submit) + ↓ (延迟 1 秒) +3. 上传听歌记录 (scrobble) + ↓ (延迟 1 秒) +4. 等待 30-60 秒 + ↓ +5. 取消收藏 (song_like) +``` + +## 优势 + +### 组合使用两个接口的好处: + +1. **relay_play_state_submit**: + - 实时播放状态同步 + - 会话追踪(sessionId) + - 播放模式记录 + - 更符合现代播放器行为 + +2. **scrobble**: + - 完整的听歌记录 + - 播放时长统计 + - 来源歌单记录 + - 用于任务完成判定 + +3. **组合效果**: + - 更真实的播放行为模拟 + - 完整的数据记录 + - 提高任务完成可靠性 + +## Pull Request + +**PR #181**: https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced/pull/181 + +**提交内容**: +- ✅ 新增 `module/relay_play_state_submit.js` +- ✅ 更新 `public/docs/home.md` +- ✅ 参数校验修复 +- ✅ 使用示例更新 + +## 测试验证 + +接口已通过测试: +``` +✓ relay_play_state_submit 成功 +✓ scrobble 成功 +✓ 组合使用正常 +``` + +## 兼容性 + +- ✅ 保持原有 `scrobble` 接口不变 +- ✅ 新增 `relay_play_state_submit` 可选使用 +- ✅ 向后兼容 +- ✅ 不影响现有功能 diff --git a/module/relay_play_state_submit.js b/module/relay_play_state_submit.js new file mode 100644 index 0000000..fd698e9 --- /dev/null +++ b/module/relay_play_state_submit.js @@ -0,0 +1,32 @@ +// 提交歌曲播放状态 + +const createOption = require('../util/option.js') +module.exports = (query, request) => { + const { id, sessionId, progress = 0, playMode = 'list_loop', type = 'song' } = query + + if (!id || !sessionId) { + return Promise.reject({ + status: 400, + body: { + code: 400, + msg: '缺少必要参数:id, sessionId', + }, + }) + } + + const playStateSubmitReq = JSON.stringify({ + resource: { + id: String(id), + type: type + }, + progress: progress, + sessionId: sessionId, + playMode: playMode + }) + + const data = { + playStateSubmitReq: playStateSubmitReq + } + + return request('/api/relay/play/state/submit', data, createOption(query, 'weapi')) +}