AIclinicalresearch/frontend-v2/src/framework/router/RouteGuard.tsx

import { ReactNode } from 'react'
import { Navigate } from 'react-router-dom'
import { usePermission } from '../permission'
import PermissionDenied from './PermissionDenied'
import type { UserVersion } from '../permission'

/**
 * 路由守卫组件
 * 
 * @description
 * 保护需要特定权限的路由，防止用户通过URL直接访问无权限页面
 * 这是权限控制的"第二道防线"（第一道是TopNavigation的过滤）
 * 
 * @version Week 2 Day 7 - 任务17
 * 
 * @example
 * ```tsx
 * <Route
 *   path="/literature/*"
 *   element={
 *     <RouteGuard requiredVersion="advanced" moduleName="AI智能文献">
 *       <ASLModule />
 *     </RouteGuard>
 *   }
 * />
 * ```
 * 
 * 工作原理：
 * 1. 用户访问 /literature 路由
 * 2. RouteGuard 检查用户权限
 * 3. 如果有权限 → 渲染子组件
 * 4. 如果无权限 → 显示 PermissionDenied 页面
 * 5. 如果未登录 → 重定向到登录页（后续实现）
 */

interface RouteGuardProps {
  /** 子组件 */
  children: ReactNode
  /** 所需权限等级 */
  requiredVersion?: UserVersion
  /** 模块名称（用于显示友好提示） */
  moduleName?: string
  /** 是否重定向到首页（默认显示无权限页面） */
  redirectToHome?: boolean
}

const RouteGuard = ({
  children,
  requiredVersion,
  moduleName,
  redirectToHome = false,
}: RouteGuardProps) => {
  const { user, isAuthenticated, checkModulePermission } = usePermission()

  // 1. 检查是否登录（后续实现真实认证）
  if (!isAuthenticated) {
    // TODO: 后续实现真实的登录流程
    // 当前阶段：用户默认已登录（MOCK_USER）
    console.warn('用户未登录，应该重定向到登录页')
    // return <Navigate to="/login" replace />
  }

  // 2. 检查权限等级
  const hasPermission = checkModulePermission(requiredVersion)

  if (!hasPermission) {
    // 记录无权限访问尝试（用于后续分析和转化优化）
    console.log('🔒 权限不足：', {
      module: moduleName,
      requiredVersion,
      currentVersion: user?.version,
      userId: user?.id,
      timestamp: new Date().toISOString(),
    })

    // 如果配置了重定向，直接返回首页
    if (redirectToHome) {
      return <Navigate to="/" replace />
    }

    // 显示无权限页面（推荐，引导用户升级）
    return (
      <PermissionDenied
        moduleName={moduleName}
        requiredVersion={requiredVersion}
        currentVersion={user?.version}
      />
    )
  }

  // 3. 有权限，渲染子组件
  return <>{children}</>
}

export default RouteGuard

/**
 * 🛡️ 路由守卫最佳实践：
 * 
 * 1. 双重防护策略：
 *    - 第一道防线：TopNavigation（用户看不到无权限模块）
 *    - 第二道防线：RouteGuard（防止URL直接访问）
 *    - 为什么需要两道？防止用户通过浏览器直接输入URL绕过导航
 * 
 * 2. 权限检查时机：
 *    ✅ 路由渲染前检查（RouteGuard）
 *    ✅ API请求前检查（后端）
 *    ✅ 组件渲染前检查（usePermission）
 * 
 * 3. 无权限时的处理策略：
 *    【推荐】显示PermissionDenied页面
 *      - 优点：引导用户升级，商业转化机会
 *      - 缺点：需要额外页面
 *    【备选】重定向到首页
 *      - 优点：简单直接
 *      - 缺点：用户体验不好，不利于转化
 * 
 * 4. 后续演进计划：
 *    【Week 2 Day 8-9】对接后端JWT认证
 *      - 实现真实的登录流程
 *      - 从token解析用户权限
 *      - 处理token过期
 *    
 *    【Week 3-4】ASL模块测试
 *      - ASL需要advanced权限
 *      - 测试权限控制是否生效
 *      - 优化无权限页面的转化率
 *    
 *    【Week 5+】完善权限系统
 *      - 动态权限配置
 *      - 功能级权限控制（不仅是模块级）
 *      - 权限变更实时生效
 * 
 * 5. 安全注意事项：
 *    ⚠️ 前端权限检查不是安全保障，仅用于用户体验
 *    ✅ 后端必须进行权限验证（真正的安全防线）
 *    ✅ 敏感数据不应该发送到前端
 *    ✅ API调用必须携带认证token
 */