# 🚀 快速参考指南

## 📋 关键配置清单

### 1. Spotify Dashboard 配置

**Redirect URIs：**
```
http://localhost:5173/callback    ← 开发环境
https://sports.rucky.cn/callback  ← 生产环境
```

配置地址：https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings

### 2. 服务器配置（解决刷新 404）

**Nginx：**
```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

**Apache：**
```apache
<Directory /var/www/sports.rucky.cn>
    AllowOverride All  # 启用 .htaccess
</Directory>
```

`.htaccess` 已自动包含在构建中！

### 3. 构建命令

```bash
# 开发
npm run dev

# 构建生产版本
npm run build

# 生产文件在 dist/ 目录
```

### 4. 部署文件

```
dist/
  ├── index.html        ← 入口文件
  ├── assets/           ← JS/CSS
  ├── .htaccess         ← Apache 配置（自动包含）
  └── _redirects        ← Vercel/Netlify 配置
```

## 🔍 快速测试

### 测试 SPA 路由

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

# 2. 本地测试
npx serve -s dist

# 3. 访问测试
http://localhost:3000/music-rhythm

# 4. 刷新页面 - 应该不会 404 ✅
```

### 测试 Spotify 授权

```bash
# 1. 确认 Redirect URI 配置正确
# 2. 访问应用
https://sports.rucky.cn/

# 3. 进入音乐律动页面
# 4. 点击"连接 Spotify 账号"
# 5. 授权后应自动返回 ✅
```

## ⚡ 常用命令

```bash
# 安装依赖
npm install

# 开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npx serve -s dist

# 检查 TypeScript
npx tsc --noEmit

# 部署（示例）
rsync -avz --delete dist/ user@sports.rucky.cn:/var/www/sports.rucky.cn/

# 重启 Nginx
sudo systemctl restart nginx

# 重启 Apache
sudo systemctl restart apache2

# 查看 Nginx 日志
sudo tail -f /var/log/nginx/error.log

# 查看 Apache 日志
sudo tail -f /var/log/apache2/error.log
```

## 📄 文档索引

| 文档 | 用途 |
|------|------|
| `QUICK_START.md` | 3 步快速开始 |
| `SPOTIFY_SETUP.md` | Spotify 详细配置 |
| `SPOTIFY_PKCE_IMPLEMENTATION.md` | **PKCE 官方实现说明** ⭐ |
| `SPOTIFY_CALLBACK_SOLUTION.md` | 授权流程说明 |
| `FIX_404_PROBLEM.md` | 解决刷新 404 问题 |
| `PRODUCTION_DEPLOYMENT.md` | 生产环境部署 |
| `nginx.conf.example` | Nginx 配置示例 |
| `public/.htaccess` | Apache 配置（自动） |

## 🎯 故障排除快速检查

### ❌ 问题：授权失败

```bash
# 检查项
☐ Redirect URI 是否为 /callback
☐ 是否包含 http://localhost:5173/callback
☐ 是否包含 https://sports.rucky.cn/callback
☐ 是否点击了 "Save" 按钮
```

### ❌ 问题：刷新 404

```bash
# 检查项
☐ Nginx 是否配置了 try_files
☐ Apache 是否启用了 AllowOverride
☐ .htaccess 是否在网站根目录
☐ 服务器是否重启
```

### ❌ 问题：播放失败

```bash
# 检查项
☐ 是否有 Spotify Premium 账号
☐ Spotify 应用是否打开
☐ 是否有活动的播放设备
☐ 授权令牌是否过期（1小时）
```

## 🔐 配置信息

**Client ID：** `4ed200672ba1421baa31b9859bd84d39`

**域名：**
- 开发：`http://localhost:5173`
- 生产：`https://sports.rucky.cn`

**授权方式：** Authorization Code Flow with PKCE
- ✅ [完全符合官方文档](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)
- ✅ 不需要 Client Secret
- ✅ 防止 CSRF 攻击（state 参数）
- ✅ 防止授权码拦截

**所需权限：**
- user-read-playback-state
- user-modify-playback-state
- user-read-currently-playing
- streaming
- user-read-email
- user-read-private
- playlist-read-private
- playlist-read-collaborative
- user-library-read

## 📞 获取帮助

遇到问题？
1. 查看对应的详细文档
2. 检查浏览器控制台错误
3. 查看服务器日志
4. 参考 Spotify 开发者社区

---

**快速开始：** `QUICK_START.md`  
**完整部署：** `PRODUCTION_DEPLOYMENT.md`  
**解决 404：** `FIX_404_PROBLEM.md`