# 认证模块

## 技术栈
- NextAuth.js v4
- Credentials Provider（用户邮箱密码）
- GitHub OAuth Provider
- JWT Session策略
- bcrypt 密码加密

## 配置 (`src/lib/auth.ts`)

### 用户认证
- 邮箱+密码注册/登录
- 用户数据存储在User表
- 密码bcrypt加密
- GitHub OAuth登录（自动创建/关联用户）
- **OAuth 竞态处理**: GitHub OAuth 并发创建用户时 P2002 唯一约束冲突自动回退 findFirst
- 登录频率限制: 7次/分钟

### 登录流程
1. 用户输入邮箱+密码
2. 检查登录频率限制
3. 查询User表获取用户
4. bcrypt.compare验证密码
5. 返回用户信息（id, email, name, role）
6. JWT回调将用户信息加入token
7. Session回调将token信息传递给session

### GitHub OAuth流程
1. 用户点击GitHub登录
2. 重定向到GitHub授权
3. 回调获取profile信息
4. 检查oauthProvider+oauthId是否已存在
5. 不存在则创建新用户
6. 返回用户信息

### Session策略
- 使用JWT，不使用数据库session
- JWT密钥: `NEXTAUTH_SECRET` 环境变量
- Session有效期: 30天
- Token包含: id, role

### 回调函数
- `signIn`: GitHub OAuth自动创建用户
- `jwt`: 登录时将用户信息加入token
- `session`: 将token中的用户信息传递给session

## 路由保护 (`src/middleware.ts`)

### 保护规则
- 保护 `/admin` 下所有路由
- 保护 `/api/admin/:path*` 路由
- 保护 `/api/user/:path*` 路由
- 跳过 `/admin/login`
- 使用NextAuth middleware进行认证检查

### 权限检查
- 检查token是否存在
- 检查role是否为admin或vip
- 未登录重定向到 /admin/login
- 无权限返回401/403

## 管理员API认证 (`src/lib/admin-auth.ts`)

### getAdminSession
- 获取当前会话
- 验证用户角色
- 支持role字符串和roleId双重验证
- 缓存机制（React cache）

### requireAdmin中间件
- 所有 `/api/admin/` 路由必须使用requireAdmin中间件
- 验证流程: 检查session → 验证角色
- 返回401/403错误响应

### getUserPermissionKeys
- 获取用户权限键集合
- 基于roleId关联Role表查询
- 缓存机制

### requirePermission
- 细粒度权限点校验
- 检查permissionKeys是否包含指定key
- 返回403如果缺少权限

### getAllUserPermissions
- 获取当前用户全部权限集合
- 支持admin角色（返回全部权限）
- 支持roleId关联角色

## 前端权限Hook (`src/lib/use-permission.ts`)

### usePermission
- 客户端Hook
- 获取当前用户权限
- 缓存机制
- 提供方法:
  - `can(key)` — 检查单个权限
  - `canAny(keys)` — 检查任一权限
  - `canAll(keys)` — 检查全部权限
  - `refresh` — 刷新权限

## 登录页
- 管理员登录: `src/app/(admin)/admin/login/page.tsx` (原生HTML表单 + CSRF Token)
- 用户登录: `src/app/login/page.tsx` (NextAuth Credentials + GitHub OAuth)
- 用户登录弹窗: `src/components/common/LoginModal.tsx`
- 登录表单: `src/components/common/LoginForm.tsx`

## 环境变量
```
NEXTAUTH_URL=http://localhost:8301
NEXTAUTH_SECRET=zhuiguang-ai-dev-secret
GITHUB_CLIENT_ID=<github-oauth-client-id>
GITHUB_CLIENT_SECRET=<github-oauth-secret>
```