文档

认证系统 API

SmartCV 用户认证系统 API 文档，包含登录、注册、会话管理等功能

更新时间: 2024/12/30

SmartCV 使用基于 NextAuth.js 的认证系统，支持多种认证方式，包括邮箱密码登录和 OAuth 社交登录。

🔐 认证方式

支持的认证方式

邮箱密码登录: 传统的用户名密码认证
Google OAuth: Google 账户登录
GitHub OAuth: GitHub 账户登录
微信登录: 微信扫码登录（计划中）

会话管理

SmartCV 使用服务端会话管理，会话信息存储在安全的 HTTP-only Cookie 中。

📋 API 端点

1. 用户注册

端点: POST /api/register

描述: 创建新用户账户

请求体:

{
  "email": "[email protected]",
  "password": "securePassword123",
  "name": "张三"
}

响应:

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "[email protected]",
    "name": "张三",
    "emailVerified": false,
    "createdAt": "2024-12-30T10:00:00Z"
  }
}

错误响应:

{
  "error": "邮箱已被注册",
  "code": "EMAIL_ALREADY_EXISTS"
}

2. 用户登录

端点: POST /api/auth/signin

描述: 用户登录（由 NextAuth.js 处理）

请求体:

{
  "email": "[email protected]",
  "password": "securePassword123",
  "callbackUrl": "/dashboard"
}

响应: 重定向到指定页面或返回会话信息

3. 用户登出

端点: POST /api/auth/signout

描述: 用户登出，清除会话

请求: 需要有效的会话 Cookie

响应: 重定向到登录页面

4. 获取会话信息

端点: GET /api/auth/session

描述: 获取当前用户的会话信息

响应:

{
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "name": "张三",
    "image": "https://avatar.url",
    "subscriptionType": "FREE"
  },
  "expires": "2024-12-31T10:00:00Z"
}

5. 邮箱验证

端点: POST /api/verify-email

描述: 验证用户邮箱

请求体:

{
  "token": "verification_token_here"
}

响应:

{
  "success": true,
  "message": "邮箱验证成功"
}

6. 重发验证邮件

端点: POST /api/resend-verification

描述: 重新发送邮箱验证邮件

请求体:

{
  "email": "[email protected]"
}

响应:

{
  "success": true,
  "message": "验证邮件已发送"
}

7. 忘记密码

端点: POST /api/forgot-password

描述: 发送密码重置邮件

请求体:

{
  "email": "[email protected]"
}

响应:

{
  "success": true,
  "message": "密码重置邮件已发送"
}

8. 重置密码

端点: POST /api/reset-password

描述: 使用重置令牌重置密码

请求体:

{
  "token": "reset_token_here",
  "password": "newSecurePassword123"
}

响应:

{
  "success": true,
  "message": "密码重置成功"
}

🔒 OAuth 登录

Google OAuth

端点: GET /api/auth/signin/google

描述: 重定向到 Google OAuth 授权页面

参数:

callbackUrl: 登录成功后的回调地址

GitHub OAuth

端点: GET /api/auth/signin/github

描述: 重定向到 GitHub OAuth 授权页面

参数:

callbackUrl: 登录成功后的回调地址

🛡️ 安全机制

密码安全

加密: 使用 bcrypt 进行密码哈希
复杂度要求: 至少 8 位字符，包含字母和数字
盐值: 每个密码使用唯一的盐值

会话安全

HTTP-only Cookie: 防止 XSS 攻击
Secure Cookie: HTTPS 环境下启用
SameSite: 防止 CSRF 攻击
过期时间: 7 天后自动过期

令牌安全

JWT: 使用 HS256 算法签名
短期有效: 访问令牌 1 小时有效
刷新令牌: 用于获取新的访问令牌

📝 使用示例

JavaScript 示例

// 用户注册
async function registerUser(email, password, name) {
  const response = await fetch('/api/register', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email,
      password,
      name
    })
  })
 
  const data = await response.json()
  if (data.success) {
    console.log('注册成功:', data.data)
  } else {
    console.error('注册失败:', data.error)
  }
}
 
// 获取会话信息
async function getSession() {
  const response = await fetch('/api/auth/session')
  const session = await response.json()
 
  if (session.user) {
    console.log('当前用户:', session.user)
  } else {
    console.log('用户未登录')
  }
}
 
// 使用 next-auth/react
import { useSession, signIn, signOut } from 'next-auth/react'
 
function AuthComponent() {
  const { data: session, status } = useSession()
 
  if (status === 'loading') return <p>加载中...</p>
 
  if (session) {
    return (
      <>
        <p>已登录: {session.user.email}</p>
        <button onClick={() => signOut()}>登出</button>
      </>
    )
  }
 
  return (
    <>
      <p>未登录</p>
      <button onClick={() => signIn()}>登录</button>
    </>
  )
}

cURL 示例

# 用户注册
curl -X POST https://smartcv.cc/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123",
    "name": "张三"
  }'
 
# 获取会话信息
curl -X GET https://smartcv.cc/api/auth/session \
  -H "Cookie: next-auth.session-token=your-session-token"
 
# 邮箱验证
curl -X POST https://smartcv.cc/api/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "verification_token_here"}'

❌ 错误处理

常见错误码

错误码	HTTP 状态	描述
`EMAIL_ALREADY_EXISTS`	400	邮箱已被注册
`INVALID_CREDENTIALS`	401	登录凭据无效
`EMAIL_NOT_VERIFIED`	403	邮箱未验证
`TOKEN_EXPIRED`	403	令牌已过期
`TOKEN_INVALID`	403	令牌无效
`USER_NOT_FOUND`	404	用户不存在
`WEAK_PASSWORD`	422	密码强度不足

错误响应格式

{
  "error": "邮箱已被注册",
  "code": "EMAIL_ALREADY_EXISTS",
  "details": {
    "field": "email",
    "value": "[email protected]"
  }
}

🔧 开发配置

环境变量

# NextAuth.js 配置
NEXTAUTH_URL=https://smartcv.cc
NEXTAUTH_SECRET=your-secret-key
 
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
 
# GitHub OAuth
GITHUB_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret
 
# 邮件服务
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your-app-password

回调 URL 配置

确保在 OAuth 提供商处配置正确的回调 URL：

Google: https://smartcv.cc/api/auth/callback/google
GitHub: https://smartcv.cc/api/auth/callback/github

下一步

📄 简历管理

了解如何通过 API 管理用户简历

查看简历 API →

👤 用户管理

学习用户信息和账户管理相关 API

查看用户 API →

遇到问题？联系我们获取帮助

快速入门用户指南技术支持

最后更新: 2024/12/30 •改进建议