# 🎵 音乐律动应用 - Spotify 集成完整指南

一个基于步频的智能音乐播放应用，集成了 Spotify Web API。

## 📦 已完成的功能

### ✅ 核心功能
- 🎯 **步频预设模式**：散步、快走、慢跑、跑步、冲刺 5 种模式
- 👆 **手动步频检测**：点击节拍自动计算 BPM
- 🎹 **节奏生成模式**：根据步频自动生成节奏音乐
- 📁 **本地播放列表**：上传本地音乐文件播放
- 🎧 **Spotify 集成**：播放 Spotify 数百万首歌曲

### ✅ Spotify 功能
- 🔐 OAuth 2.0 授权
- 🎯 根据 BPM 推荐歌曲
- 🔍 关键词搜索（歌曲、艺术家、专辑）
- 📋 访问用户歌单
- ▶️ 完整播放控制（播放、暂停、上一首、下一首）
- 🖼️ 显示歌曲封面和信息
- 💾 自动保存授权状态

### ✅ 视觉效果
- 🎨 Canvas 粒子动画
- 💫 节拍脉冲效果
- 🌈 渐变色彩设计
- 📱 响应式布局

## 🚀 快速开始

### 开发环境

```bash
# 1. 安装依赖
npm install

# 2. 启动开发服务器
npm run dev

# 3. 打开浏览器
# http://localhost:5173/
```

### 生产环境

```bash
# 1. 构建
npm run build

# 2. 部署 dist 目录到服务器
# https://sports.rucky.cn/
```

## ⚙️ Spotify 配置

### 配置信息
- **Client ID：** `4ed200672ba1421baa31b9859bd84d39`
- **开发环境 URI：** `http://localhost:5173/`
- **生产环境 URI：** `https://sports.rucky.cn/`

### 必需操作

在 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings) 中添加 Redirect URIs：

1. 点击 "Edit Settings"
2. 在 "Redirect URIs" 中添加：
   - `http://localhost:5173/`
   - `https://sports.rucky.cn/`
3. 点击 "Save"

### 前置要求
- ✅ Spotify Premium 账号（必需，免费账号无法播放）
- ✅ Spotify 桌面或移动应用已安装并登录

## 📖 文档目录

- **[QUICK_START.md](./QUICK_START.md)** - 3 步快速启动指南
- **[SPOTIFY_SETUP.md](./SPOTIFY_SETUP.md)** - Spotify 详细配置教程
- **[PRODUCTION_DEPLOYMENT.md](./PRODUCTION_DEPLOYMENT.md)** - 生产环境部署指南

## 🎯 使用场景

1. **跑步运动**
   - 设置跑步模式（170 BPM）
   - 根据步频推荐匹配音乐
   - 保持节奏稳定

2. **健身房训练**
   - 根据训练强度选择步频
   - 播放激励性音乐
   - 提升运动表现

3. **日常散步**
   - 轻松的散步模式（80 BPM）
   - 播放舒缓音乐
   - 享受悠闲时光

## 🔧 技术栈

- **前端框架：** Vue 3 + TypeScript
- **构建工具：** Vite
- **路由：** Vue Router
- **音频处理：** Web Audio API
- **图形渲染：** Canvas API
- **音乐服务：** Spotify Web API
- **授权方式：** Authorization Code Flow with PKCE ✅
  - [完全符合 Spotify 官方文档](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)

## 📂 项目结构

```
newToy/
├── src/
│   ├── views/
│   │   ├── Home.vue              # 首页
│   │   ├── MusicRhythm.vue       # 音乐律动主页面
│   │   └── ...                   # 其他页面
│   ├── services/
│   │   └── spotifyService.ts     # Spotify API 服务
│   ├── router.ts                 # 路由配置
│   └── main.ts                   # 入口文件
├── docs/
│   ├── QUICK_START.md            # 快速开始
│   ├── SPOTIFY_SETUP.md          # Spotify 配置
│   └── PRODUCTION_DEPLOYMENT.md  # 部署指南
├── vite.config.js                # Vite 配置
└── package.json                  # 依赖配置
```

## 🎵 三种播放模式

### 1. 节奏模式 🎹
- 根据步频自动生成节奏音乐
- 使用 Web Audio API 合成音频
- 实时同步视觉效果

### 2. 本地播放 📁
- 上传本地音乐文件
- 支持多种音频格式
- 完整的播放列表管理

### 3. Spotify 模式 🎧
- 搜索 Spotify 海量曲库
- 根据 BPM 智能推荐
- 访问个人歌单

## 🎨 界面预览

### 主界面
- 步频显示和模式选择
- 可视化效果展示
- 播放器控制面板

### Spotify 界面
- 三种搜索模式切换
- 搜索结果列表
- 当前播放信息

## 🔐 安全性

- ✅ Client ID 可以公开
- ✅ 使用 OAuth 2.0 Implicit Grant Flow
- ✅ 访问令牌仅存储在本地
- ✅ 令牌有效期 1 小时
- ✅ 生产环境强制 HTTPS

## 📱 移动端支持

- ✅ 响应式设计
- ✅ 触摸事件优化
- ✅ 移动端播放控制
- ✅ 自适应布局

## ⚠️ 常见问题

### Spotify 授权失败
- 检查 Redirect URI 配置
- 确保 URL 完全匹配（包括斜杠）
- 清除浏览器缓存重试

### 播放失败
- 确保有 Premium 账号
- 打开 Spotify 应用激活设备
- 检查网络连接

### 搜索不到歌曲
- 检查授权是否过期
- 重新连接 Spotify 账号
- 检查搜索关键词

## 🔗 相关链接

- [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
- [Spotify Web API 文档](https://developer.spotify.com/documentation/web-api)
- [你的应用设置](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
- [Spotify 开发者社区](https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer)

## 📊 API 使用限制

- **授权令牌：** 1 小时有效期
- **搜索请求：** 无明确限制，但建议合理使用
- **播放控制：** 需要 Premium 账号
- **推荐 API：** 最多返回 100 个结果

## 🎯 未来计划

- [ ] 添加歌词显示
- [ ] 支持创建播放列表
- [ ] 添加音频分析可视化
- [ ] 支持多设备切换
- [ ] 添加运动数据统计
- [ ] 集成其他音乐平台

## 💡 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可

MIT License

---

**开始你的音乐律动之旅！** 🎉

访问开发环境：http://localhost:5173/

访问生产环境：https://sports.rucky.cn/