forked from 77media/video-flow
随堂测验
This commit is contained in:
parent
5ff071f6c0
commit
7ae003a133
290
docs/jiekou.md
290
docs/jiekou.md
@ -1,241 +1,121 @@
|
||||
# Google OAuth 前端改造指南
|
||||
# Google OAuth 前端接入说明
|
||||
|
||||
## 📋 改造目标
|
||||
让Google OAuth注册用户也能享受积分发放和邀请奖励功能。
|
||||
该文档面向前端同学，描述最新的 Google 登录/注册接入方式。
|
||||
|
||||
## 🔄 新的流程设计
|
||||
---
|
||||
|
||||
## 一、整体流程
|
||||
|
||||
### **改造后流程**：
|
||||
```
|
||||
1. 前端接收Google OAuth回调
|
||||
2. 前端 → Java验证接口（只验证，不创建用户）
|
||||
3. 前端 → Python注册接口（创建用户 + 积分发放）
|
||||
4. 返回完整的用户信息和token
|
||||
用户 → Google 授权 → 回到前端回调页
|
||||
前端回调页读取 code/state → 调用 Python /api/oauth/google
|
||||
Python 返回 token/user 给前端 → 前端完成登录态落地
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 前端修改步骤
|
||||
## 二、Google 控制台配置
|
||||
|
||||
### 📍 修改文件
|
||||
**文件**: `video-flow/app/api/auth/google/callback/route.ts`
|
||||
在 Google Cloud Console → API 与服务 → 凭据 → 选择"Web 应用的客户端 ID"：
|
||||
|
||||
### 🔧 核心修改
|
||||
### Authorized JavaScript origins（已授权的 JavaScript 来源）
|
||||
- `https://www.movieflow.net`
|
||||
- `https://www.movieflow.ai`
|
||||
|
||||
#### **第一步：调用Java验证接口**
|
||||
### Authorized redirect URIs（已授权的重定向 URI）
|
||||
- `https://www.movieflow.net/api/auth/google/callback`
|
||||
- `https://www.movieflow.ai/api/auth/google/callback`
|
||||
|
||||
本地调试（可选）：
|
||||
- JavaScript origins: `http://localhost:3000`
|
||||
- Redirect URIs: `http://localhost:3000/api/auth/google/callback`
|
||||
|
||||
---
|
||||
|
||||
## 三、前端调用
|
||||
|
||||
### 第一步：Google 授权回调
|
||||
在前端回调页（`/api/auth/google/callback`）读取 Google 返回的 `code` 与 `state`。
|
||||
|
||||
### 第二步：调用 Python 接口
|
||||
- **路径**：`POST ${NEXT_PUBLIC_SMARTVIDEO_URL}/api/oauth/google`
|
||||
- **请求体**：
|
||||
```json
|
||||
{
|
||||
"code": "string",
|
||||
"state": "string",
|
||||
"invite_code": "string | null"
|
||||
}
|
||||
```
|
||||
|
||||
- **响应**：
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"token": "string",
|
||||
"user": {
|
||||
"userId": "string",
|
||||
"userName": "string",
|
||||
"name": "string",
|
||||
"email": "string",
|
||||
"authType": "GOOGLE",
|
||||
"avatar": "string",
|
||||
"isNewUser": true
|
||||
},
|
||||
"message": "Google OAuth successful"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 前端代码示例
|
||||
```typescript
|
||||
// 调用Java callback进行Google Token验证（不创建用户）
|
||||
const javaBaseUrl = process.env.NEXT_PUBLIC_JAVA_URL || 'https://auth.test.movieflow.ai';
|
||||
|
||||
const verifyResponse = await fetch(`${javaBaseUrl}/api/auth/google/callback`, {
|
||||
const baseUrl = process.env.NEXT_PUBLIC_SMARTVIDEO_URL;
|
||||
const res = await fetch(`${baseUrl}/api/oauth/google`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json',
|
||||
'Accept': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
code: code, // Google authorization code
|
||||
state: state, // state参数
|
||||
inviteCode: inviteCode, // 邀请码
|
||||
skipUserCreation: true // 🔑 关键：只验证不创建用户
|
||||
})
|
||||
body: JSON.stringify({ code, state, invite_code })
|
||||
});
|
||||
|
||||
const verifyResult = await verifyResponse.json();
|
||||
```
|
||||
|
||||
#### **第二步：调用Python注册接口**
|
||||
```typescript
|
||||
// 调用Python注册接口进行用户创建和积分发放
|
||||
const smartvideoBaseUrl = process.env.NEXT_PUBLIC_SMARTVIDEO_URL || 'https://smartvideo.test.movieflow.ai';
|
||||
|
||||
const registerResponse = await fetch(`${smartvideoBaseUrl}/api/user_fission/register_with_invite`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email: verifyResult.data.email,
|
||||
name: verifyResult.data.name,
|
||||
auth_type: 'GOOGLE',
|
||||
google_user_info: verifyResult.data,
|
||||
invite_code: inviteCode || stateData.inviteCode || undefined
|
||||
})
|
||||
});
|
||||
|
||||
const registerResult = await registerResponse.json();
|
||||
```
|
||||
|
||||
#### **第三步：返回统一格式结果**
|
||||
```typescript
|
||||
return NextResponse.json({
|
||||
success: true,
|
||||
data: {
|
||||
token: registerResult.data.token,
|
||||
user: {
|
||||
userId: registerResult.data.user_id,
|
||||
userName: registerResult.data.name,
|
||||
name: registerResult.data.name,
|
||||
email: registerResult.data.email,
|
||||
authType: registerResult.data.auth_type,
|
||||
isNewUser: true
|
||||
},
|
||||
message: 'Google OAuth registration successful with credit rewards'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 后端接口文档
|
||||
|
||||
### 🔵 Java验证接口
|
||||
|
||||
#### **接口地址**
|
||||
```
|
||||
POST /api/auth/google/callback
|
||||
```
|
||||
|
||||
#### **请求参数**
|
||||
```typescript
|
||||
{
|
||||
code: string, // Google authorization code
|
||||
state: string, // state参数（可包含邀请码信息）
|
||||
inviteCode?: string, // 邀请码（可选）
|
||||
skipUserCreation: boolean // true=只验证不创建用户
|
||||
}
|
||||
```
|
||||
|
||||
#### **成功响应**
|
||||
```typescript
|
||||
{
|
||||
success: true,
|
||||
message: "Google Token验证成功",
|
||||
data: {
|
||||
email: string, // 用户邮箱
|
||||
name: string, // 用户姓名
|
||||
picture: string, // 头像URL
|
||||
googleId: string, // Google用户ID
|
||||
verified: boolean, // 是否已验证
|
||||
inviteCode: string // 邀请码（如果有）
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **错误响应**
|
||||
```typescript
|
||||
{
|
||||
success: false,
|
||||
error: "TOKEN_EXCHANGE_FAILED" | "INVALID_ID_TOKEN",
|
||||
message: string
|
||||
const result = await res.json();
|
||||
if (result.success) {
|
||||
const { token, user } = result.data;
|
||||
// 持久化 token & user
|
||||
} else {
|
||||
// 统一错误提示 result.message
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔵 Python注册接口
|
||||
## 四、环境变量
|
||||
|
||||
#### **接口地址**
|
||||
```
|
||||
POST /api/user_fission/register_with_invite
|
||||
```
|
||||
|
||||
#### **请求参数**
|
||||
```typescript
|
||||
{
|
||||
email: string, // 用户邮箱
|
||||
name?: string, // 用户姓名（可选）
|
||||
auth_type: "GOOGLE", // 认证类型（固定为GOOGLE）
|
||||
google_user_info: { // Google用户信息（来自Java验证接口）
|
||||
email: string,
|
||||
name: string,
|
||||
picture: string,
|
||||
googleId: string,
|
||||
verified: boolean,
|
||||
inviteCode?: string
|
||||
},
|
||||
invite_code?: string // 邀请码（可选）
|
||||
}
|
||||
```
|
||||
|
||||
#### **成功响应**
|
||||
```typescript
|
||||
{
|
||||
successful: true, // 注意：是 successful 不是 success
|
||||
message: "Google OAuth注册成功",
|
||||
data: {
|
||||
user_id: string, // 用户ID（UUID格式）
|
||||
email: string, // 用户邮箱
|
||||
name: string, // 用户姓名
|
||||
auth_type: "GOOGLE", // 认证类型
|
||||
invite_code?: string, // 邀请码
|
||||
token?: string // 认证token（如果有）
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **错误响应**
|
||||
```typescript
|
||||
{
|
||||
successful: false,
|
||||
message: string, // 错误信息
|
||||
detail?: string // 详细错误信息
|
||||
}
|
||||
```
|
||||
- `NEXT_PUBLIC_SMARTVIDEO_URL`：后端 Python 服务地址
|
||||
|
||||
---
|
||||
|
||||
## 🔧 环境变量配置
|
||||
## 五、错误处理
|
||||
|
||||
确保以下环境变量已配置：
|
||||
常见错误码：
|
||||
- `GOOGLE_TOKEN_EXCHANGE_FAILED`：授权码交换失败
|
||||
- `INVALID_ID_TOKEN`：ID Token 无效
|
||||
- `UPSTREAM_AUTH_ERROR`：用户服务异常
|
||||
|
||||
```bash
|
||||
# Java认证服务地址
|
||||
NEXT_PUBLIC_JAVA_URL=https://auth.test.movieflow.ai
|
||||
|
||||
# Python积分服务地址
|
||||
NEXT_PUBLIC_SMARTVIDEO_URL=https://smartvideo.test.movieflow.ai
|
||||
```
|
||||
前端统一处理：基于 `success=false` 与 `message` 提示用户。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要注意事项
|
||||
## 六、安全建议
|
||||
|
||||
### 🔍 **关键变更**
|
||||
1. **接口变更**: `/api/auth/google/login` → `/api/auth/google/callback`
|
||||
2. **参数变更**:
|
||||
- 移除: `idToken`, `action`
|
||||
- 新增: `code`, `state`, `skipUserCreation: true`
|
||||
3. **响应字段**: Python返回 `successful`，Java返回 `success`
|
||||
4. **用户ID字段**: Python返回 `user_id`，前端映射为 `userId`
|
||||
|
||||
### 🚨 **错误处理**
|
||||
- Java验证失败 → 停止流程，返回错误
|
||||
- Python注册失败 → 返回详细错误信息
|
||||
- 网络异常 → 提供用户友好提示
|
||||
|
||||
### 🧪 **测试检查点**
|
||||
- [ ] Google OAuth验证是否成功
|
||||
- [ ] 用户是否正确创建并获得积分
|
||||
- [ ] 邀请码功能是否正常
|
||||
- [ ] 错误处理是否完善
|
||||
- [ ] 前端页面跳转是否正常
|
||||
- 启用 PKCE
|
||||
- 在 `state` 中绑定 CSRF 防护信息
|
||||
- 确保回调地址与发起授权时的 `redirect_uri` 完全一致
|
||||
|
||||
---
|
||||
|
||||
## 🎯 预期效果
|
||||
|
||||
改造完成后，Google OAuth用户将获得：
|
||||
|
||||
✅ **注册奖励积分**
|
||||
✅ **邀请码奖励功能**
|
||||
✅ **邀请人奖励积分**
|
||||
✅ **统一的用户体验**
|
||||
✅ **完整的积分记录**
|
||||
|
||||
---
|
||||
|
||||
*文档版本: v2.0*
|
||||
*更新时间: 2025-01-22*
|
||||
*适用范围: video-flow前端项目*
|
||||
文档版本：v4.0
|
||||
更新时间：2025-09-23
|
||||
适用范围：video-flow 前端项目
|
||||
Loading…
x
Reference in New Issue
Block a user