video-flow-b/docs/jiekou.md

# Google OAuth 前端改造指南

## 📋 改造目标
让Google OAuth注册用户也能享受积分发放和邀请奖励功能。

## 🔄 新的流程设计

### **改造后流程**：
```
1. 前端接收Google OAuth回调
2. 前端 → Java验证接口（只验证，不创建用户）
3. 前端 → Python注册接口（创建用户 + 积分发放）
4. 返回完整的用户信息和token
```

---

## 🛠️ 前端修改步骤

### 📍 修改文件
**文件**: `video-flow/app/api/auth/google/callback/route.ts`

### 🔧 核心修改

#### **第一步：调用Java验证接口**
```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`, {
  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         // 🔑 关键：只验证不创建用户
  })
});

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
}
```

---

### 🔵 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                  // 详细错误信息
}
```

---

## 🔧 环境变量配置

确保以下环境变量已配置：

```bash
# Java认证服务地址
NEXT_PUBLIC_JAVA_URL=https://auth.test.movieflow.ai

# Python积分服务地址  
NEXT_PUBLIC_SMARTVIDEO_URL=https://smartvideo.test.movieflow.ai
```

---

## ⚠️ 重要注意事项

### 🔍 **关键变更**
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验证是否成功
- [ ] 用户是否正确创建并获得积分
- [ ] 邀请码功能是否正常
- [ ] 错误处理是否完善
- [ ] 前端页面跳转是否正常

---

## 🎯 预期效果

改造完成后，Google OAuth用户将获得：

✅ **注册奖励积分**  
✅ **邀请码奖励功能**  
✅ **邀请人奖励积分**  
✅ **统一的用户体验**  
✅ **完整的积分记录**

---

*文档版本: v2.0*  
*更新时间: 2025-01-22*  
*适用范围: video-flow前端项目*