From 7ae003a1335092b09ddad5aec21690d6113aba08 Mon Sep 17 00:00:00 2001 From: Zixin Zhou Date: Tue, 23 Sep 2025 15:12:08 +0800 Subject: [PATCH] =?UTF-8?q?=E9=9A=8F=E5=A0=82=E6=B5=8B=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/jiekou.md | 280 ++++++++++++++----------------------------------- 1 file changed, 80 insertions(+), 200 deletions(-) diff --git a/docs/jiekou.md b/docs/jiekou.md index 977af09..9d9983f 100644 --- a/docs/jiekou.md +++ b/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验证接口** -```typescript -// 调用Java callback进行Google Token验证（不创建用户） -const javaBaseUrl = process.env.NEXT_PUBLIC_JAVA_URL || 'https://auth.test.movieflow.ai'; +### Authorized redirect URIs（已授权的重定向 URI） +- `https://www.movieflow.net/api/auth/google/callback` +- `https://www.movieflow.ai/api/auth/google/callback` -const verifyResponse = await fetch(`${javaBaseUrl}/api/auth/google/callback`, { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'Accept': 'application/json', - }, - body: JSON.stringify({ - code: code, // Google authorization code - state: state, // state参数 - inviteCode: inviteCode, // 邀请码 - skipUserCreation: true // 🔑 关键：只验证不创建用户 - }) -}); +本地调试（可选）： +- JavaScript origins: `http://localhost:3000` +- Redirect URIs: `http://localhost:3000/api/auth/google/callback` -const verifyResult = await verifyResponse.json(); +--- + +## 三、前端调用 + +### 第一步：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" +} ``` -#### **第二步：调用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 +- **响应**： +```json +{ + "success": true, + "data": { + "token": "string", + "user": { + "userId": "string", + "userName": "string", + "name": "string", + "email": "string", + "authType": "GOOGLE", + "avatar": "string", + "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 // 邀请码（如果有） + "message": "Google OAuth successful" } } ``` -#### **错误响应** +### 前端代码示例 ```typescript -{ - success: false, - error: "TOKEN_EXCHANGE_FAILED" | "INVALID_ID_TOKEN", - message: string -} -``` - ---- - -### 🔵 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 +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' }, - invite_code?: string // 邀请码（可选） -} -``` + body: JSON.stringify({ code, state, invite_code }) +}); -#### **成功响应** -```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 // 详细错误信息 +const result = await res.json(); +if (result.success) { + const { token, user } = result.data; + // 持久化 token & user +} else { + // 统一错误提示 result.message } ``` --- -## 🔧 环境变量配置 +## 四、环境变量 -确保以下环境变量已配置： - -```bash -# Java认证服务地址 -NEXT_PUBLIC_JAVA_URL=https://auth.test.movieflow.ai - -# Python积分服务地址 -NEXT_PUBLIC_SMARTVIDEO_URL=https://smartvideo.test.movieflow.ai -``` +- `NEXT_PUBLIC_SMARTVIDEO_URL`：后端 Python 服务地址 --- -## ⚠️ 重要注意事项 +## 五、错误处理 -### 🔍 **关键变更** -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` +常见错误码： +- `GOOGLE_TOKEN_EXCHANGE_FAILED`：授权码交换失败 +- `INVALID_ID_TOKEN`：ID Token 无效 +- `UPSTREAM_AUTH_ERROR`：用户服务异常 -### 🚨 **错误处理** -- Java验证失败 → 停止流程，返回错误 -- Python注册失败 → 返回详细错误信息 -- 网络异常 → 提供用户友好提示 - -### 🧪 **测试检查点** -- [ ] Google OAuth验证是否成功 -- [ ] 用户是否正确创建并获得积分 -- [ ] 邀请码功能是否正常 -- [ ] 错误处理是否完善 -- [ ] 前端页面跳转是否正常 +前端统一处理：基于 `success=false` 与 `message` 提示用户。 --- -## 🎯 预期效果 +## 六、安全建议 -改造完成后，Google OAuth用户将获得： - -✅ **注册奖励积分** -✅ **邀请码奖励功能** -✅ **邀请人奖励积分** -✅ **统一的用户体验** -✅ **完整的积分记录** +- 启用 PKCE +- 在 `state` 中绑定 CSRF 防护信息 +- 确保回调地址与发起授权时的 `redirect_uri` 完全一致 --- -*文档版本: v2.0* -*更新时间: 2025-01-22* -*适用范围: video-flow前端项目* \ No newline at end of file +文档版本：v4.0 +更新时间：2025-09-23 +适用范围：video-flow 前端项目 \ No newline at end of file