# JWT 认证系统实现说明

## 概述

本项目实现了一个基于JWT的前端认证系统，配合OAuth2.0统一认证使用。该系统在用户通过OAuth2.0认证后，生成一个前端专用的JWT Token，包含用户信息和权限数据。

## 核心功能

### 1. JWT生成与管理 (`app/utils/jwt.ts`)
- 生成包含用户信息的JWT
- 验证JWT的有效性
- 检查JWT过期状态
- 解析JWT获取用户信息

### 2. 认证服务集成 (`app/api/login/auth.server.ts`)
- 在OAuth2.0登录成功后自动生成JWT
- 在Token刷新时重新生成JWT
- JWT自动存储在session中

### 3. 前端认证Hook (`app/hooks/useAuth.ts`)
- 提供便捷的认证状态获取
- JWT验证和过期检查
- 用户权限检查功能

## 使用方法

### 在Loader中返回认证信息

```typescript
// app/routes/your-route.tsx
export async function loader({ request }: LoaderFunctionArgs) {
  const { getUserSession } = await import("~/api/login/auth.server");
  const sessionData = await getUserSession(request);
  
  return Response.json({
    // 你的其他数据
    yourData: "...",
    
    // 认证信息
    isAuthenticated: sessionData.isAuthenticated,
    userInfo: sessionData.userInfo,
    userRole: sessionData.userRole,
    frontendJWT: sessionData.frontendJWT
  });
}
```

### 在组件中使用认证信息

```typescript
// 在你的React组件中
import { useAuth } from '~/hooks/useAuth';

export default function YourComponent() {
  const auth = useAuth();
  
  // 检查认证状态
  if (!auth.isAuthenticated) {
    return <div>请先登录</div>;
  }
  
  // 使用用户信息
  return (
    <div>
      <h1>欢迎，{auth.nickName}</h1>
      <p>用户ID: {auth.userId}</p>
      <p>角色: {auth.userRole}</p>
      
      {/* 权限检查 */}
      {auth.isAdmin() && (
        <button>管理员操作</button>
      )}
      
      {auth.hasRole('developer') && (
        <button>开发者操作</button>
      )}
    </div>
  );
}
```

### JWT验证和状态检查

```typescript
const auth = useAuth();

// 验证JWT
const jwtValidation = auth.validateJWT();
if (!jwtValidation.valid) {
  console.error('JWT无效:', jwtValidation.error);
}

// 检查是否即将过期
if (auth.isJWTExpiringSoon()) {
  console.log('JWT即将过期，建议刷新页面');
}

// 获取过期时间
const expiration = auth.getJWTExpiration();
if (expiration) {
  console.log('JWT过期时间:', new Date(expiration * 1000));
}
```

## JWT载荷结构

```typescript
{
  // 标准字段
  sub: string;          // 用户唯一标识(来自IDaaS)
  iss: string;          // 发行者: 'docreview-system'
  aud: string;          // 受众: 'docreview-frontend'
  iat: number;          // 签发时间
  exp: number;          // 过期时间
  
  // 自定义用户信息字段
  user_id: string;      // 数据库中的用户ID
  username: string;     // 用户名
  nick_name: string;    // 用户昵称
  email?: string;       // 邮箱
  phone_number?: string; // 手机号
  ou_id: string;        // 组织单位ID
  ou_name: string;      // 组织单位名称
  is_leader: boolean;   // 是否为负责人
  user_role: string;    // 用户角色
}
```

## 安全特性

1. **过期时间控制**: JWT过期时间设置为OAuth Token过期时间的90%，确保JWT在OAuth Token之前过期
2. **自动刷新**: 当OAuth Token刷新时，自动重新生成JWT
3. **签名验证**: 使用HS256算法和固定密钥进行签名验证
4. **过期检查**: 提供5分钟缓冲时间的过期预警

## 调试工具

使用 `AuthDebugInfo` 组件在开发阶段查看JWT状态：

```typescript
import { AuthDebugInfo } from '~/components/auth/AuthDebugInfo';

export default function DebugPage() {
  return (
    <div>
      <h1>认证调试页面</h1>
      <AuthDebugInfo />
    </div>
  );
}
```

## 配置说明

### JWT密钥配置
在 `app/utils/jwt.ts` 中修改JWT密钥：

```typescript
// 生产环境中应该从环境变量读取
const JWT_SECRET = 'your-super-secret-jwt-key-change-this-in-production-2024';
```

### JWT配置参数
```typescript
const JWT_CONFIG = {
  algorithm: 'HS256',
  issuer: 'docreview-system',
  audience: 'docreview-frontend'
};
```

## 注意事项

1. **生产环境安全**: 
   - JWT密钥应该从环境变量读取
   - 删除或隐藏 `AuthDebugInfo` 组件
   - 考虑使用更强的签名算法

2. **性能优化**:
   - JWT验证在前端进行，减少服务器压力
   - 使用session存储避免频繁重新生成

3. **错误处理**:
   - JWT验证失败时应该引导用户重新登录
   - 过期检查应该在关键操作前进行

## 工作流程

1. 用户通过OAuth2.0登录
2. `callback.tsx` 接收认证结果并保存用户信息到数据库
3. 根据保存的用户信息生成JWT
4. JWT存储在session中
5. 后续请求通过 `getUserSession` 检查JWT状态
6. 前端通过 `useAuth` hook 使用认证信息
7. 当OAuth Token刷新时，自动重新生成JWT

## 扩展功能

可以考虑的扩展功能：
- JWT黑名单机制
- 多设备登录管理
- 权限细粒度控制
- JWT刷新接口
- 客户端JWT存储（LocalStorage/SessionStorage）