# Spotify Web API 集成指南

本应用已集成 [Spotify Web API](https://developer.spotify.com/documentation/web-api)，可以直接播放 Spotify 上的音乐。

## 🎯 前置要求

1. **Spotify Premium 账号**（必需）
   - 只有 Premium 账号才能使用 Web Playback API
   - 免费账号只能查看数据，无法控制播放

2. **Spotify 开发者账号**（免费）
   - 需要注册开发者应用获取 Client ID

## 📝 设置步骤

### 第一步：注册 Spotify 开发者应用

1. 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. 使用你的 Spotify 账号登录
3. 点击 **"Create app"** 按钮
4. 填写应用信息：
   - **App name**: `Music Rhythm App`（可自定义）
   - **App description**: `A music app with BPM detection`（可自定义）
   - **Website**: `http://localhost:5173`（开发环境）
   - **Redirect URI**: 
     - `http://localhost:5173/`（开发环境，重要！必须精确匹配）
     - `https://sports.rucky.cn/`（生产环境）
   - **Which APIs are you planning to use?**: 选择 `Web API`
5. 勾选同意服务条款
6. 点击 **"Save"** 保存

⚠️ **注意：** 本应用使用 **Authorization Code Flow with PKCE**，这是 Spotify 推荐的安全授权方式，不需要 Client Secret。

### 第二步：获取 Client ID

1. 在应用详情页面，找到 **"Client ID"**
2. 复制 **Client ID**
3. **不需要** Client Secret（PKCE 流程不需要密钥，更安全）

### 第三步：配置应用

✅ **Client ID 已配置完成！**

当前使用的 Client ID: `4ed200672ba1421baa31b9859bd84d39`

**重要：请确保在 Spotify Dashboard 中配置了正确的 Redirect URI**

在你的 Spotify 应用设置中，必须添加以下 Redirect URI：

**开发环境：**
```
http://localhost:5173/
```

**如果使用其他端口，请相应修改，例如：**
```
http://localhost:5174/
http://localhost:3000/
```

如何设置：
1. 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. 找到你的应用
3. 点击 **"Edit Settings"**
4. 在 **"Redirect URIs"** 输入框中添加 `http://localhost:5173/`
5. 点击 **"Add"** 按钮
6. 点击 **"Save"** 保存设置

### 第四步：配置生产环境的 Redirect URI（必需）

**你的生产环境 URI：** `https://sports.rucky.cn`

请在 Spotify Dashboard 中添加以下 Redirect URIs：

**开发环境：**
```
http://localhost:5173/callback
```

**生产环境：**
```
https://sports.rucky.cn/callback
```

⚠️ **重要说明：**
- ✅ 使用 `/callback` 路径（符合 [Spotify 官方文档示例](https://developer.spotify.com/documentation/web-api/tutorials/code-flow)）
- ✅ 必须完全匹配，包括协议和路径
- ✅ 必须同时添加开发和生产环境的 URI
- ✅ 授权成功后会自动跳转回音乐律动页面

设置步骤：
1. 访问 [你的应用设置](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
2. 点击 **"Edit Settings"**
3. 在 **"Redirect URIs"** 中添加 `/callback` 路径：
   - `http://localhost:5173/callback` （开发环境）
   - `https://sports.rucky.cn/callback` （生产环境）
4. 点击 **"Add"** 添加每个 URI
5. 点击 **"Save"** 保存

✅ **符合官方文档！** 使用专门的 `/callback` 路由处理授权回调，更清晰规范。

## 🎵 使用说明

### 基本使用流程

1. **启动应用**
   ```bash
   npm run dev
   ```

2. **进入音乐律动页面**
   - 在首页点击 "🎵 音乐律动·步频检测" 卡片

3. **连接 Spotify**
   - 点击 "Spotify" 标签页
   - 点击 "连接 Spotify 账号" 按钮
   - 在弹出的页面中授权应用访问你的 Spotify 账号
   - 授权成功后会自动返回应用

4. **播放音乐**

   **方式一：根据步频推荐**
   - 选择运动模式（散步、慢跑等）
   - 点击 "🎯 匹配步频" 标签
   - 点击 "🎵 推荐歌曲" 按钮
   - 系统会根据当前步频（BPM）推荐匹配的歌曲
   - 点击任意歌曲开始播放

   **方式二：关键词搜索**
   - 点击 "🔍 关键词搜索" 标签
   - 输入歌曲名、艺术家或专辑名
   - 按回车或点击 "搜索" 按钮
   - 点击任意歌曲开始播放

   **方式三：我的歌单**
   - 点击 "📋 我的歌单" 标签
   - 选择你的 Spotify 歌单
   - 从歌单中选择歌曲播放

5. **播放控制**
   - 支持播放/暂停、上一首、下一首
   - 显示当前播放的歌曲信息和封面

## ⚠️ 常见问题

### Q1: 提示"播放失败"怎么办？

确保满足以下条件：
1. ✅ 你有 Spotify Premium 账号
2. ✅ Spotify 桌面应用或手机应用已打开并登录
3. ✅ 至少有一个活动的播放设备
4. ✅ 授权令牌未过期（令牌有效期 1 小时）

### Q2: 找不到可用设备？

解决方法：
1. 打开 Spotify 桌面应用或手机应用
2. 在 Spotify 应用中随便播放一首歌（这会激活设备）
3. 返回 Web 应用重试

### Q3: 搜索不到歌曲？

可能的原因：
1. 授权令牌过期 - 点击 "退出" 后重新连接
2. 网络问题 - 检查网络连接
3. Spotify API 限制 - 等待几分钟后重试

### Q4: 授权后返回应用但显示未授权？

解决方法：
1. 检查 Redirect URI 是否完全匹配
2. 清除浏览器缓存和 localStorage
3. 重新授权

## 🔒 关于 PKCE 授权流程

本应用使用 **Authorization Code Flow with PKCE (Proof Key for Code Exchange)**，这是 Spotify 推荐的最安全的授权方式。

### PKCE 的优势

1. **更安全**：不需要 Client Secret，避免密钥泄露风险
2. **适合单页应用**：专为前端应用设计
3. **防止授权码拦截**：使用动态生成的 code_verifier 和 code_challenge
4. **Spotify 推荐**：官方推荐方式，Implicit Grant Flow 已被弃用

### 授权流程

1. 生成随机的 `code_verifier`（64位随机字符串）
2. 使用 SHA-256 哈希生成 `code_challenge`
3. 用户授权后获得 `authorization_code`
4. 使用 `code_verifier` 交换 `access_token`

### 与旧版本的区别

- ❌ 旧版：使用 `response_type=token`（Implicit Grant，已弃用）
- ✅ 新版：使用 `response_type=code` + PKCE（Authorization Code Flow）

## 🔒 安全注意事项

1. **Client ID 是公开的**
   - Client ID 可以公开，不需要隐藏
   - 不需要 Client Secret（PKCE 流程不使用）

2. **访问令牌**
   - 访问令牌存储在 localStorage 中
   - 令牌有效期为 1 小时
   - 不要与他人分享你的访问令牌

3. **Code Verifier**
   - 动态生成，每次授权都不同
   - 临时存储在 localStorage，使用后立即删除

4. **生产环境**
   - 必须使用 HTTPS
   - 限制 Redirect URI 到你的域名

## 📚 API 文档参考

- [Spotify Web API 文档](https://developer.spotify.com/documentation/web-api)
- [授权指南](https://developer.spotify.com/documentation/web-api/tutorials/getting-started)
- [播放控制 API](https://developer.spotify.com/documentation/web-api/reference/start-a-users-playback)
- [搜索 API](https://developer.spotify.com/documentation/web-api/reference/search)
- [推荐 API](https://developer.spotify.com/documentation/web-api/reference/get-recommendations)

## 🎨 功能特性

- ✅ OAuth 2.0 授权流程
- ✅ 根据 BPM 推荐歌曲
- ✅ 关键词搜索
- ✅ 访问用户歌单
- ✅ 播放控制（播放、暂停、上一首、下一首）
- ✅ 显示歌曲信息和封面
- ✅ 自动保存授权状态
- ✅ 优雅的错误处理

## 🔄 更新日志

- 2025-11-23: 初始版本，集成 Spotify Web API

---

如有问题，请参考 [Spotify 开发者社区](https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer) 获取帮助。