crush-level-web/docs/GoogleOAuth-QuickStart.md

# Google OAuth 快速开始指南

## 5 分钟快速集成

### 步骤 1: 获取 Google OAuth 凭据

1. 访问 [Google Cloud Console](https://console.cloud.google.com/)
2. 创建新项目或选择现有项目
3. 在左侧菜单选择 "API 和服务" > "凭据"
4. 点击 "创建凭据" > "OAuth 客户端 ID"
5. 选择应用类型为 "Web 应用"
6. 配置授权重定向 URI：
   ```
   http://localhost:3000/api/auth/google/callback
   ```
7. 点击"创建"并复制客户端 ID

### 步骤 2: 配置环境变量

在项目根目录创建 `.env.local` 文件：

```bash
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_GOOGLE_CLIENT_ID=你的客户端ID
```

### 步骤 3: 重启开发服务器

```bash
npm run dev
```

### 步骤 4: 测试登录

1. 访问 http://localhost:3000/login
2. 点击 "Continue with Google" 按钮
3. 选择 Google 账号并授权
4. 应该会重定向回应用并完成登录

## 文件清单

已创建的文件：

- ✅ `src/lib/oauth/google.ts` - Google OAuth 配置
- ✅ `src/app/(auth)/login/components/GoogleButton.tsx` - Google 登录按钮组件
- ✅ `src/app/api/auth/google/callback/route.ts` - OAuth 回调路由
- ✅ `src/app/(auth)/login/components/login-form.tsx` - 已更新使用 GoogleButton

## 工作流程

```
用户点击按钮
    ↓
GoogleButton.handleGoogleLogin()
    ↓
跳转到 Google 授权页面
    ↓
用户授权
    ↓
Google 重定向到 /api/auth/google/callback
    ↓
API 路由提取 code 并重定向到 /login?google_code=xxx
    ↓
GoogleButton.useEffect() 检测到 google_code
    ↓
调用后端登录接口 (thirdType: Google)
    ↓
登录成功，跳转到首页
```

## 后端接口要求

后端需要处理以下登录请求：

```typescript
POST /api/auth/login

{
  "appClient": "WEB",
  "deviceCode": "设备ID",
  "thirdToken": "Google授权码",
  "thirdType": "GOOGLE"
}
```

后端需要：

1. 使用授权码向 Google 交换 access_token
2. 使用 access_token 获取用户信息
3. 创建或更新用户
4. 返回应用的登录 token

## 常见问题

### Q: 点击按钮后没有跳转？

A: 检查浏览器控制台是否有错误，确认环境变量已正确配置。

### Q: 回调后显示错误？

A: 检查 Google Cloud Console 中的回调 URL 配置是否正确。

### Q: 登录接口调用失败？

A: 确认后端接口已实现并支持 Google 登录。

## 生产环境部署

### 1. 更新 Google OAuth 配置

在 Google Cloud Console 添加生产环境回调 URL：

```
https://your-domain.com/api/auth/google/callback
```

### 2. 更新环境变量

```bash
NEXT_PUBLIC_APP_URL=https://your-domain.com
NEXT_PUBLIC_GOOGLE_CLIENT_ID=生产环境客户端ID
```

### 3. 部署

确保在部署平台（Vercel/Netlify）配置了正确的环境变量。

## 下一步

- [ ] 测试完整的登录流程
- [ ] 添加错误处理和用户反馈
- [ ] 实现登出功能
- [ ] 添加用户信息展示
- [ ] 考虑添加 Apple 登录

## 技术支持

如有问题，请参考：

- [完整文档](./GoogleOAuth.md)
- [环境变量配置](./EnvironmentVariables.md)
- [Google OAuth 官方文档](https://developers.google.com/identity/protocols/oauth2)