# Google OAuth 前端接入说明

该文档面向前端同学，描述最新的 Google 登录/注册接入方式。

---

## 一、整体流程

```
用户 → Google 授权 → 回到前端回调页
前端回调页读取 code/state → 调用 Python /api/oauth/google
Python 返回 token/user 给前端 → 前端完成登录态落地
```

---

## 二、Google 控制台配置

在 Google Cloud Console → API 与服务 → 凭据 → 选择"Web 应用的客户端 ID"：

### Authorized JavaScript origins（已授权的 JavaScript 来源）
- `https://www.movieflow.net`
- `https://www.movieflow.ai`

### 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
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' 
  },
  body: JSON.stringify({ code, state, invite_code })
});

const result = await res.json();
if (result.success) {
  const { token, user } = result.data;
  // 持久化 token & user
} else {
  // 统一错误提示 result.message
}
```

---

## 四、环境变量

- `NEXT_PUBLIC_SMARTVIDEO_URL`：后端 Python 服务地址

---

## 五、错误处理

常见错误码：
- `GOOGLE_TOKEN_EXCHANGE_FAILED`：授权码交换失败
- `INVALID_ID_TOKEN`：ID Token 无效  
- `UPSTREAM_AUTH_ERROR`：用户服务异常

前端统一处理：基于 `success=false` 与 `message` 提示用户。

---

## 六、安全建议

- 启用 PKCE
- 在 `state` 中绑定 CSRF 防护信息
- 确保回调地址与发起授权时的 `redirect_uri` 完全一致

---

文档版本：v4.0  
更新时间：2025-09-23  
适用范围：video-flow-b 前端项目