nuxt-app/docs/superpowers/specs/2026-05-26-oauth2-design.md

OAuth2 模块化功能设计方案

创建日期：2026-05-26 状态：已批准

---

一、架构概览

┌─────────────────────────────────────────────────────────┐
│                     前端 (Vue)                          │
│  /pages/auth/login.vue (集成 GitHub 登录按钮)           │
└─────────────────────┬───────────────────────────────────┘
                      │ 1. 点击登录
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   后端 API (Nitro)                       │
│  ┌─────────────────────────────────────────────────┐   │
│  │ OAuthModule (核心调度器)                          │   │
│  │  - registerProvider() 注册 Provider              │   │
│  │  - getAuthorizationUrl() 生成授权 URL            │   │
│  │  - handleCallback() 处理回调                     │   │
│  │  - bindAccount() 绑定账号                        │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌────────────────┐  ┌────────────────┐               │
│  │ GitHubProvider  │  │ GoogleProvider  │  ... (可扩展)  │
│  │ (implements)    │  │ (implements)    │               │
│  └────────────────┘  └────────────────┘               │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ OAuthStateStore (state 临时存储，5min TTL)       │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ AuthService (现有认证服务)                       │   │
│  │  - getCurrentUser()                             │   │
│  │  - loginUser() / registerUser()                 │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│                  数据库 (SQLite)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   users    │  │  sessions  │  │oauth_accounts│     │
│  └─────────────┘  └─────────────┘  └─────────────┘   │
└─────────────────────────────────────────────────────────┘

核心设计原则：

• 配置驱动 — 内置 Provider 通过 oauth.providers.ts 配置注册，零代码添加新 Provider
• 策略模式 — 每个 Provider 是独立策略类，实现统一接口
• 最小改动 — 集成到现有登录页，不影响现有认证逻辑

---

二、核心模块设计

2.1 OAuth Provider 接口

// packages/oauth/src/providers/base.ts
export interface OAuthProvider {
  name: string;                    // 'github' | 'google'
  icon: string;                    // emoji 或 Icon 组件名
  clientId: string;
  clientSecret: string;
  authorizeUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scopes: string[];                // 请求的权限范围
  // 特定字段映射（不同 Provider 的返回字段不同）
  mapUserInfo(raw: Record<string, unknown>): OAuthUserInfo;
}

export type OAuthUserInfo = {
  provider: string;
  providerUserId: string;          // 第三方平台的用户 ID
  username?: string;
  email?: string;
  avatar?: string;
};

2.2 OAuth 模块核心

// packages/oauth/src/core/oauth-manager.ts
export class OAuthManager {
  // 注册 Provider
  registerProvider(provider: OAuthProvider): void;

  // 生成授权 URL（含 state）
  async getAuthorizationUrl(providerName: string): Promise<string>;

  // 处理回调（交换 token，获取用户信息）
  async handleCallback(providerName: string, code: string, state: string): Promise<OAuthCallbackResult>;

  // 绑定账号（已登录用户绑定第三方账号）
  async bindAccount(userId: number, providerName: string, providerUserId: string): Promise<void>;

  // 解绑账号
  async unbindAccount(userId: number, providerName: string): Promise<void>;

  // 获取用户已绑定的 OAuth 账号列表
  async getUserBindings(userId: number): Promise<OAuthBinding[]>;
}

export type OAuthCallbackResult = {
  success: boolean;
  isNewUser: boolean;
  user?: MinimalUser;
  requiresBinding: boolean;         // 账号已存在但未绑定，需用户确认
  bindingToken?: string;            // 临时 binding token
};

export type OAuthBinding = {
  id: number;
  provider: string;
  username: string | null;
  email: string | null;
  avatar: string | null;
  boundAt: Date;
};

2.3 State 管理（防止 CSRF）

// packages/oauth/src/core/oauth-state-store.ts
// 内存 Map + 5min TTL 过期清理
// State 包含: providerName, redirectUri, createdAt, userId(可选)

State 存储结构：

type OAuthState = {
  providerName: string;
  redirectUri: string;
  createdAt: number;      // timestamp
  userId?: number;        // 绑定模式下才有值
  isBinding: boolean;     // 是否为绑定模式
};

---

三、数据库设计

3.1 oauth_accounts 表

CREATE TABLE `oauth_accounts` (
  `id` integer PRIMARY KEY AUTOINCREMENT,
  `user_id` integer NOT NULL,
  `provider` text NOT NULL,
  `provider_user_id` text NOT NULL,
  `username` text,
  `email` text,
  `avatar` text,
  `created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
  `updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
  UNIQUE(`provider`, `provider_user_id`),
  FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE cascade
);

CREATE INDEX `oauth_accounts_user_id_idx` ON `oauth_accounts` (`user_id`);

索引设计： provider + provider_user_id 唯一索引确保不能重复绑定。

---

四、API 设计

方法	路径	说明
GET	/api/auth/oauth/:provider/authorize	生成授权 URL，重定向到 GitHub
GET	/api/auth/oauth/:provider/callback	GitHub 回调，处理 token 交换
POST	/api/auth/oauth/bind	已登录用户绑定 OAuth 账号
DELETE	/api/auth/oauth/:provider/unbind	解绑 OAuth 账号
GET	/api/auth/oauth/bindings	获取当前用户的绑定列表
GET	/api/auth/oauth/:provider/status	查询某 Provider 的绑定状态

4.1 授权接口

GET /api/auth/oauth/:provider/authorize

Query Parameters:
  - bind: number (可选) 绑定模式下传递 1
  - redirect_uri: string (可选) 自定义回调跳转地址

Response: 302 重定向到 Provider 授权页面

4.2 回调接口

GET /api/auth/oauth/:provider/callback

Query Parameters:
  - code: string Provider 授权码
  - state: string 防止 CSRF 的状态令牌

Response: 302 重定向到前端页面
  - 登录成功：/auth/login?oauth_success=1
  - 绑定成功：/profile?bind_success=1
  - 失败：/auth/login?oauth_error=xxx

4.3 绑定接口

POST /api/auth/oauth/bind

Body:
{
  bindingToken: string;  // 回调时返回的临时 token
}

Response:
{
  success: true,
  binding: {
    provider: string;
    username: string | null;
  }
}

4.4 解绑接口

DELETE /api/auth/oauth/:provider/unbind

Response:
{
  success: true
}

4.5 绑定列表接口

GET /api/auth/oauth/bindings

Response:
{
  bindings: [
    {
      id: number;
      provider: string;
      username: string | null;
      email: string | null;
      avatar: string | null;
      boundAt: Date;
    }
  ]
}

4.6 单个 Provider 绑定状态

GET /api/auth/oauth/:provider/status

Response:
{
  bound: boolean;
  binding?: {
    id: number;
    username: string | null;
  }
}

---

五、流程图

5.1 新用户 OAuth 登录流程

┌──────────────────────────────────────────────────────────────────┐
│                         GitHub OAuth 登录流程                      │
└──────────────────────────────────────────────────────────────────┘

  用户                    前端                    后端                    GitHub
   │                       │                       │                       │
   │  点击 GitHub 登录按钮  │                       │                       │
   │──────────────────────>│                       │                       │
   │                       │                       │                       │
   │                       │ GET /api/auth/oauth/github/authorize       │
   │                       │────────────────────────────────────────────>
   │                       │                       │                       │
   │                       │                       │  1. 生成 state        │
   │                       │                       │  2. 存储 state        │
   │                       │                       │  3. 拼接授权 URL       │
   │                       │                       │<────────────────────────────────────────────
   │                       │                       │                       │
   │<──────────────────────│ 302 重定向到 GitHub   │                       │
   │                       │                       │                       │
   │  在 GitHub 授权页面    │                       │                       │
   │  确认授权              │                       │                       │
   │───────────────────────│───────────────────────│──────────────────────>
   │                       │                       │                       │
   │                       │                       │  GitHub 回调          │
   │                       │                       │  ?code=xxx&state=xxx  │
   │                       │                       │<──────────────────────│
   │                       │                       │                       │
   │                       │                       │  验证 state           │
   │                       │                       │  用 code 换 token     │
   │                       │                       │  获取用户信息          │
   │                       │                       │──────────────────────>
   │                       │                       │                       │
   │                       │                       │  创建/查找用户         │
   │                       │                       │  创建 session         │
   │                       │                       │                       │
   │<──────────────────────│ 302 重定向到 /auth/login?oauth_success=1    │
   │                       │                       │                       │
   │  检测 url参数          │                       │                       │
   │  刷新 session          │                       │                       │
   │──────────────────────>│                       │                       │
   │                       │                       │                       │
   │                       │ GET /api/auth/session                       │
   │                       │────────────────────────────────────────────>
   │                       │                       │                       │
   │                       │<─────────────────────────────────────────────│ 登录成功
   │                       │                       │                       │
   │  显示登录成功         │                       │                       │
   │                       │                       │                       │

5.2 已注册用户绑定 GitHub 流程

┌──────────────────────────────────────────────────────────────────┐
│                      账号绑定流程                                  │
└──────────────────────────────────────────────────────────────────┘

  已登录用户               前端                    后端                    GitHub
   │                       │                       │                       │
   │  点击绑定 GitHub      │                       │                       │
   │──────────────────────>│                       │                       │
   │                       │                       │                       │
   │                       │ GET /api/auth/oauth/github/authorize?bind=1 │
   │                       │────────────────────────────────────────────>
   │                       │                       │                       │
   │                       │                       │  生成 binding state    │
   │                       │                       │  包含 userId          │
   │                       │                       │                       │
   │<──────────────────────│ 302 重定向到 GitHub   │                       │
   │                       │                       │                       │
   │  授权                 │                       │                       │
   │───────────────────────│───────────────────────│──────────────────────>
   │                       │                       │                       │
   │                       │                       │  GitHub 回调          │
   │                       │                       │  验证 binding state   │
   │                       │                       │  用 code 换 token     │
   │                       │                       │  获取用户信息          │
   │                       │                       │                       │
   │                       │                       │  插入 oauth_accounts  │
   │                       │                       │                       │
   │<──────────────────────│ 302 重定向到 /profile?bind_success=1        │
   │                       │                       │                       │
   │  显示绑定成功         │                       │                       │
   │                       │                       │                       │

5.3 GitHub 用户映射关系

GitHub API 返回字段 -> OAuthUserInfo 映射 (GitHubProvider)

GitHub 返回:
{
  "id": 123456,
  "login": "username",
  "email": "user@example.com",     // 需要 user:email 权限
  "avatar_url": "https://..."
}

映射后:
{
  provider: "github",
  providerUserId: "123456",
  username: "username",
  email: "user@example.com",
  avatar: "https://..."
}

---

六、现有登录页集成

在 /pages/auth/login.vue 增加：

<!-- 现有登录表单 -->
<template>
  <div class="login-form">
    <UForm ...> ... </UForm>

    <!-- 新增：第三方登录分割线 -->
    <div class="divider">
      <span>或</span>
    </div>

    <!-- 新增：OAuth 登录按钮 -->
    <button @click="loginWithGithub" class="btn-github">
      <Icon name="github" /> GitHub 登录
    </button>
  </div>
</template>

<script setup>
async function loginWithGithub() {
  // 跳转到后端授权接口
  window.location.href = '/api/auth/oauth/github/authorize';
}
</script>

---

七、模块化扩展（添加 Google Provider）

只需在配置文件中添加：

// packages/oauth/src/providers/index.ts
export const oauthProviders = {
  github: new GitHubProvider({
    clientId: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
  }),
  google: new GoogleProvider({
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    scopes: ['openid', 'email', 'profile'],
  }),
};

零代码新增 Provider — 只需配置。

---

八、错误处理

错误码	说明	处理方式
OAUTH_PROVIDER_NOT_FOUND	不支持的 Provider	提示用户
OAUTH_STATE_INVALID	state 验证失败	CSRF 攻击风险，清除跳转
OAUTH_STATE_EXPIRED	state 过期（>5min）	提示重新授权
OAUTH_TOKEN_EXCHANGE_FAILED	token 交换失败	提示重试
OAUTH_USER_INFO_FAILED	获取用户信息失败	提示重试
OAUTH_ALREADY_BIND	账号已绑定其他用户	提示解绑后重试
OAUTH_BINDING_USER_MISMATCH	绑定用户不匹配	重新登录授权

---

九、配置项

// .env.example
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

// OAuth 配置
OAUTH_STATE_TTL_MS=300000  # 5 minutes
OAUTH_CALLBACK_URL=/api/auth/oauth  # 回调基础路径

---

十、文件结构

packages/oauth/
├── src/
│   ├── index.ts                    # 模块入口
│   ├── core/
│   │   ├── oauth-manager.ts         # 核心管理器
│   │   ├── oauth-state-store.ts    # State 存储
│   │   └── oauth-error.ts          # 错误类
│   ├── providers/
│   │   ├── base.ts                 # Provider 接口
│   │   ├── github.ts               # GitHub Provider
│   │   ├── google.ts               # Google Provider (预留)
│   │   └── index.ts                # Provider 导出
│   ├── db/
│   │   ├── schema.ts               # oauth_accounts 表定义
│   │   └── queries.ts              # 数据库操作
│   └── api/
│       ├── authorize.get.ts        # 授权接口
│       ├── callback.get.ts         # 回调接口
│       ├── bind.post.ts            # 绑定接口
│       ├── unbind.delete.ts        # 解绑接口
│       ├── bindings.get.ts         # 绑定列表接口
│       └── status.get.ts           # 绑定状态接口
├── package.json
└── tsconfig.json

docs/superpowers/
├── specs/
│   └── 2026-05-26-oauth2-design.md  # 本设计文档
└── oauth2/
    ├── README.md                    # 使用指南
    ├── PROVIDERS.md                  # Provider 配置文档
    ├── FLOW.md                      # 流程图详解
    └── API.md                       # API 接口文档

---

十一、后续扩展

1. 更多 Provider — Google（国内需翻墙）、微信（需商户资质）
2. OAuth 端点管理 — 后台管理 OAuth 配置，支持动态添加
3. 登录日志 — 记录 OAuth 登录历史，用于安全审计
4. 强制绑定 — 首次登录后强制绑定邮箱或手机号
5. OAuth 链接有效期 — 支持在个人中心查看和解绑 OAuth 账号