# 🚀 Spotify 集成快速启动指南

您的 Spotify Client ID 已配置完成！

## ✨ 授权方式升级

本应用使用 **Authorization Code Flow with PKCE**（最新、最安全的授权方式）：
- ✅ 不需要 Client Secret
- ✅ 更安全的授权流程
- ✅ Spotify 官方推荐
- ✅ 防止授权码拦截攻击
- ✅ [100% 符合官方文档](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)

详细实现说明见：[SPOTIFY_PKCE_IMPLEMENTATION.md](./SPOTIFY_PKCE_IMPLEMENTATION.md)

## ⚡ 快速开始（3步）

### 第 1 步：配置 Spotify Dashboard ⚙️

**必须完成！** 否则授权会失败

1. 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
2. 在 **"Redirect URIs"** 中添加以下两个地址：
   
   **开发环境：**
   ```
   http://localhost:5173/callback
   ```
   
   **生产环境：**
   ```
   https://sports.rucky.cn/callback
   ```
   
   ⚠️ 注意：使用 `/callback` 路径（符合官方文档示例），两个地址都要添加！

3. 点击 **"Add"** 添加每个地址
4. 点击 **"Save"** 保存设置

### 第 2 步：启动应用 🚀

```bash
npm run dev
```

### 第 3 步：使用 Spotify 🎵

**开发环境：**
1. 打开浏览器访问：`http://localhost:5173/`
2. 点击 **"音乐律动·步频检测"**
3. 点击 **"Spotify"** 标签页
4. 点击 **"连接 Spotify 账号"** 按钮
5. 授权后开始使用！

**生产环境：**
1. 打开浏览器访问：`https://sports.rucky.cn/`
2. 按照相同步骤操作即可

## 📋 使用前检查清单

请确保以下条件都满足：

- [ ] ✅ 你有 **Spotify Premium** 账号（免费账号无法播放）
- [ ] ✅ 在 Spotify Dashboard 中添加了 `http://localhost:5173/` 作为 Redirect URI
- [ ] ✅ Spotify 桌面应用或手机 App 已打开并登录
- [ ] ✅ 应用已启动并运行在 `http://localhost:5173/`

## 🎯 三种播放方式

### 1️⃣ 根据步频推荐（智能匹配）
- 选择运动模式（散步、慢跑、跑步等）
- 点击 **"🎯 匹配步频"** 标签
- 点击 **"🎵 推荐歌曲"** 按钮
- 系统会根据你的步频（BPM）推荐最匹配的音乐
- 点击任意歌曲开始播放

**示例：**
- 散步 80 BPM → 推荐轻松慢歌
- 跑步 170 BPM → 推荐快节奏电音

### 2️⃣ 关键词搜索
- 点击 **"🔍 关键词搜索"** 标签
- 输入歌曲名、艺术家或专辑
- 点击搜索或按回车
- 点击任意歌曲开始播放

**示例搜索：**
- 歌曲名：`Shape of You`
- 艺术家：`Taylor Swift`
- 专辑：`1989`

### 3️⃣ 我的歌单
- 点击 **"📋 我的歌单"** 标签
- 浏览你的 Spotify 歌单
- 点击歌单查看歌曲列表
- 点击任意歌曲开始播放

## ❓ 常见问题快速解决

### 🚫 授权失败 / Redirect URI mismatch

**原因：** Redirect URI 配置不正确

**解决：**
1. 检查 Spotify Dashboard 中的 Redirect URI 是否为 `http://localhost:5173/`（包含最后的斜杠）
2. 如果使用其他端口，请相应修改
3. 保存后重新授权

### 🚫 播放失败 / No active device found

**原因：** 没有活动的播放设备

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

### 🚫 搜索不到歌曲

**原因：** Token 过期或网络问题

**解决：**
1. 点击右上角 **"退出"** 按钮
2. 重新点击 **"连接 Spotify 账号"**
3. 重新授权

### 🚫 提示需要 Premium 账号

**原因：** 使用了免费账号

**解决：**
- Spotify Web Playback API 仅支持 Premium 账号
- 可以注册 Premium 试用或升级账号
- 免费账号可以搜索和查看，但无法播放

## 🎨 功能亮点

- 🎯 **智能步频匹配**：根据你的运动步频推荐最合适的音乐
- 🔍 **强大搜索**：搜索 Spotify 数百万首歌曲
- 📋 **歌单管理**：访问你的所有 Spotify 歌单
- 🎵 **实时播放控制**：播放、暂停、上一首、下一首
- 🖼️ **精美展示**：显示歌曲封面和详细信息
- 💾 **自动保存**：授权状态自动保存，下次无需重新登录

## 🔗 相关链接

- [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
- [你的应用设置](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
- [Spotify Web API 文档](https://developer.spotify.com/documentation/web-api)
- [完整设置指南](./SPOTIFY_SETUP.md)

---

**现在就开始享受音乐吧！** 🎉