diff --git a/app/api/auth/user-routes.ts b/app/api/auth/user-routes.ts
index 96e4a25..558bbb3 100644
--- a/app/api/auth/user-routes.ts
+++ b/app/api/auth/user-routes.ts
@@ -1,7 +1,34 @@
 import { toastService } from '~/components/ui';
-import { postgrestGet } from '../postgrest-client';
+import { apiRequest } from '../axios-client';
 
-// 路由数据接口
+// 后端返回的路由数据接口
+export interface BackendRouteInfo {
+  id: number;
+  route_path: string;
+  route_name: string;
+  component: string;
+  parent_id: number | null;
+  route_title: string;
+  icon: string | null;
+  sort_order: number;
+  is_hidden: boolean;
+  is_cache: boolean;
+  meta: string;
+  children?: BackendRouteInfo[];
+}
+
+// 后端API响应接口
+export interface BackendRoutesResponse {
+  code: number;
+  msg: string;
+  data: {
+    user_id: number;
+    username: string;
+    routes: BackendRouteInfo[];
+  };
+}
+
+// 旧的路由数据接口（保留用于兼容）
 export interface RouteInfo {
   id: number;
   path: string;
@@ -458,82 +485,87 @@ const FALLBACK_MENU_DATA: Record<string, MenuItem[]> = {
 };
 
 /**
- * 根据角色获取用户可访问的路由
- * @param roleKey 角色标识 (如: 'admin', 'common', 'deptLeader', 'groupLeader')
+ * 根据角色获取用户可访问的路由（调用后端统一接口）
+ * @param roleKey 角色标识 (如: 'admin', 'common', 'deptLeader', 'groupLeader') - 暂时不使用，后端通过JWT自动识别
+ * @param jwt JWT token
  * @returns 用户可访问的路由列表
  */
 export async function getUserRoutesByRole(roleKey: string, jwt?: string): Promise<{ success: boolean; data?: MenuItem[]; error?: string; shouldRedirectToHome?: boolean }> {
   try {
-    console.log(`获取角色 ${roleKey} 的路由权限`);
+    console.log(`🔍 [User Routes] 获取用户路由，角色: ${roleKey}`);
 
-    // 首先获取角色ID
-    const roleResult = await postgrestGet<Array<{id: number}>>("roles", {
-      filter: {
-        "role_key": `eq.${roleKey}`
-      },
-      token: jwt
-    });
-
-    if (roleResult.error || !roleResult.data || roleResult.data.length === 0) {
-      console.error("角色不存在:", roleKey);
-      toastService.error("角色不存在，请联系管理员配置权限后重新登录");
-      return { success: false, error: "角色不存在", shouldRedirectToHome: true };
+    if (!jwt) {
+      console.error('❌ [User Routes] JWT token 未提供');
+      toastService.error("认证信息缺失，请重新登录");
+      return { success: false, error: "JWT token 未提供", shouldRedirectToHome: true };
     }
 
-    const roleId = roleResult.data[0].id;
+    // 调用后端统一接口获取用户路由
+    // 注意：Authorization 头会由 axios 拦截器自动添加（从 localStorage 读取）
+    // 但为了确保使用正确的 token，这里仍然显式传递
+    const response = await apiRequest<BackendRoutesResponse>(
+      '/rbac/user/routes',  // endpoint (第一个参数)
+      {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${jwt}`
+        }
+      }  // options (第二个参数)
+    );
 
-    // 查询角色的路由权限
-    const roleRoutesResult = await postgrestGet<Array<{route_id: number}>>("role_route", {
-      filter: {
-        "role_id": `eq.${roleId}`
-      },
-      token: jwt
-    });
+    // console.log('🔍 [User Routes] 后端返回:', response);
 
-    if (roleRoutesResult.error) {
-      console.error("查询角色路由关联失败:", roleRoutesResult.error);
-      toastService.error("查询角色路由关联失败，请稍后再试");
-      return { success: false, error: "查询角色路由关联失败", shouldRedirectToHome: true };
+    // 检查响应是否成功
+    if (response.error) {
+      console.error('❌ [User Routes] API 请求失败:', response.error);
+      toastService.error(response.error);
+      return { success: false, error: response.error, shouldRedirectToHome: true };
     }
 
-    const roleRoutes = roleRoutesResult.data || [];
-    const routeIds = roleRoutes.map(item => item.route_id);
-
-    if (routeIds.length === 0) {
-      console.log(`角色 ${roleKey} 没有分配任何路由权限`);
-      toastService.error("您的角色没有分配任何路由权限，请联系管理员配置权限");
-      return { success: false, error: "角色没有分配任何路由权限", shouldRedirectToHome: true };
+    // 检查响应数据
+    if (!response.data) {
+      console.error('❌ [User Routes] 后端未返回数据');
+      toastService.error("获取路由数据失败");
+      return { success: false, error: "后端未返回数据", shouldRedirectToHome: true };
     }
 
-    // 查询具体的路由信息
-    const routesResult = await postgrestGet<RouteInfo[]>("sys_routes", {
-      filter: {
-        "id": `in.(${routeIds.join(',')})`,
-        "is_menu": "eq.1"
-      },
-      order: "parent_id,meta->>order",
-      token: jwt
-    });
+    const backendResponse = response.data;
 
-    if (routesResult.error) {
-      console.error("查询路由信息失败:", routesResult.error);
-      toastService.error("查询路由信息失败，请稍后再试");
-      return { success: false, error: "查询路由信息失败", shouldRedirectToHome: true };
+    // 检查业务状态码（后端使用 code: 0 表示成功）
+    if (backendResponse.code !== 0 && backendResponse.code !== 200) {
+      console.error(`❌ [User Routes] 后端返回错误: ${backendResponse.msg}`);
+      toastService.error(backendResponse.msg || "获取路由权限失败");
+      return { success: false, error: backendResponse.msg || "获取路由权限失败", shouldRedirectToHome: true };
     }
 
-    const routes = routesResult.data || [];
-    
-    // 构建菜单树
-    const menuItems = buildMenuTreeFromRoutes(routes);
-    
-    console.log(`角色 ${roleKey} 可访问 ${menuItems.length} 个路由`);
+    // 检查数据完整性
+    if (!backendResponse.data || !Array.isArray(backendResponse.data.routes)) {
+      console.error('❌ [User Routes] 后端未返回路由数据');
+      toastService.error("未获取到路由权限，请联系管理员配置");
+      return { success: false, error: "后端未返回路由数据", shouldRedirectToHome: true };
+    }
+
+    const routes = backendResponse.data.routes;
+
+    if (routes.length === 0) {
+      console.log(`⚠️ [User Routes] 用户没有分配任何路由权限`);
+      toastService.error("您的角色没有分配任何路由权限，请联系管理员配置");
+      return { success: false, error: "用户没有分配任何路由权限", shouldRedirectToHome: true };
+    }
+
+    // 将后端路由格式转换为前端 MenuItem 格式
+    const menuItems = convertBackendRoutesToMenuItems(routes);
+
+    console.log(`✅ [User Routes] 成功获取 ${menuItems.length} 个路由`);
+    // console.log('📋 [User Routes] 菜单数据:', menuItems);
+
     return { success: true, data: menuItems };
 
   } catch (error) {
-    console.error("获取用户路由时发生错误:", error);
+    console.error("❌ [User Routes] 获取用户路由时发生错误:", error);
     toastService.error("获取用户路由时发生错误，请稍后再试");
-    return { 
-      success: false, 
+    return {
+      success: false,
       error: `获取用户路由失败: ${error instanceof Error ? error.message : String(error)}`,
       shouldRedirectToHome: true
     };
@@ -541,14 +573,76 @@ export async function getUserRoutesByRole(roleKey: string, jwt?: string): Promis
 }
 
 /**
- * 从路由信息构建菜单树结构
+ * Element UI 图标到 RemixIcon 的映射
+ */
+const ICON_MAPPING: Record<string, string> = {
+  'el-icon-s-home': 'ri-home-line',
+  'el-icon-house': 'ri-home-4-line',
+  'el-icon-document': 'ri-file-text-line',
+  'el-icon-edit': 'ri-edit-line',
+  'el-icon-connection': 'ri-links-line',
+  'el-icon-setting': 'ri-settings-4-line',
+  'el-icon-user': 'ri-user-line',
+  'el-icon-tickets': 'ri-ticket-line',
+  'el-icon-chat-dot-round': 'ri-chat-smile-2-line',
+  'el-icon-s-order': 'ri-list-check',
+  'el-icon-s-grid': 'ri-grid-line',
+  'el-icon-s-comment': 'ri-chat-1-line',
+  'el-icon-files': 'ri-file-copy-line',
+  'el-icon-folder': 'ri-folder-line',
+  'el-icon-upload': 'ri-upload-cloud-line',
+  'el-icon-download': 'ri-download-cloud-line',
+  'el-icon-search': 'ri-search-line',
+};
+
+/**
+ * 转换 Element UI 图标为 RemixIcon
+ */
+function convertIcon(elementIcon: string | null): string {
+  if (!elementIcon) {
+    return 'ri-file-line'; // 默认图标
+  }
+  return ICON_MAPPING[elementIcon] || 'ri-file-line';
+}
+
+/**
+ * 将后端路由格式转换为前端 MenuItem 格式
+ * @param backendRoutes 后端返回的路由数组
+ * @returns MenuItem 数组
+ */
+function convertBackendRoutesToMenuItems(backendRoutes: BackendRouteInfo[]): MenuItem[] {
+  return backendRoutes
+    .filter(route => !route.is_hidden) // 过滤隐藏的路由
+    .map(route => {
+      const menuItem: MenuItem = {
+        id: route.route_name || `route-${route.id}`,
+        title: route.route_title,
+        path: route.route_path,
+        icon: convertIcon(route.icon),
+        order: route.sort_order,
+        hideBreadcrumb: route.is_hidden
+      };
+
+      // 递归处理子路由
+      if (route.children && route.children.length > 0) {
+        menuItem.children = convertBackendRoutesToMenuItems(route.children);
+      }
+
+      return menuItem;
+    })
+    .sort((a, b) => a.order - b.order); // 按 sort_order 排序
+}
+
+/**
+ * 从路由信息构建菜单树结构（旧版本，已废弃）
  * @param routes 路由信息数组
  * @returns 菜单树结构
+ * @deprecated 使用 convertBackendRoutesToMenuItems 替代
  */
 function buildMenuTreeFromRoutes(routes: RouteInfo[]): MenuItem[] {
   // 转换为MenuItem格式
   const menuMap = new Map<number, MenuItem>();
-  
+
   routes.forEach(route => {
     const menuItem: MenuItem = {
       id: route.name,
@@ -558,25 +652,25 @@ function buildMenuTreeFromRoutes(routes: RouteInfo[]): MenuItem[] {
       order: route.meta.order || 0,
       requiredRole: route.meta.requiredRole
     };
-    
+
     menuMap.set(route.id, menuItem);
   });
-  
+
   // 构建父子关系
   const rootItems: MenuItem[] = [];
   const itemsWithParent: Array<{ item: MenuItem; parentId: number }> = [];
-  
+
   routes.forEach(route => {
     const menuItem = menuMap.get(route.id);
     if (!menuItem) return;
-    
+
     if (route.parent_id === 0) {
       rootItems.push(menuItem);
     } else {
       itemsWithParent.push({ item: menuItem, parentId: route.parent_id });
     }
   });
-  
+
   // 添加子菜单
   itemsWithParent.forEach(({ item, parentId }) => {
     const parent = menuMap.get(parentId);
@@ -587,7 +681,7 @@ function buildMenuTreeFromRoutes(routes: RouteInfo[]): MenuItem[] {
       parent.children.push(item);
     }
   });
-  
+
   // 排序
   rootItems.sort((a, b) => a.order - b.order);
   rootItems.forEach(item => {
@@ -595,7 +689,7 @@ function buildMenuTreeFromRoutes(routes: RouteInfo[]): MenuItem[] {
       item.children.sort((a, b) => a.order - b.order);
     }
   });
-  
+
   return rootItems;
 }
 
@@ -609,8 +703,14 @@ export function mapUserRoleToRoleKey(userRole: string): string {
     'common': 'common',
     'admin': 'admin',
     'deptLeader': 'deptLeader',
-    'groupLeader': 'groupLeader'
+    'groupLeader': 'groupLeader',
+    // 添加常见的后端角色映射
+    'super_admin': 'admin',
+    'system_admin': 'admin',
+    'user': 'common',
+    'developer': 'admin'
   };
-  
-  return roleMapping[userRole];
+
+  // 如果找不到映射，返回 userRole 本身（假设后端已经返回了正确的 role_key）
+  return roleMapping[userRole] || userRole || 'common';
 } 
\ No newline at end of file
diff --git a/app/api/axios-client.ts b/app/api/axios-client.ts
index 99dbff4..d993532 100644
--- a/app/api/axios-client.ts
+++ b/app/api/axios-client.ts
@@ -43,6 +43,86 @@ const axiosInstance = axios.create({
   }
 });
 
+// 请求白名单 - 这些接口不需要添加 Authorization 头
+const AUTH_WHITELIST = [
+  '/auth/login',
+  '/auth/refresh',
+  '/auth/register',
+  '/oauth/token',
+  '/oauth/userinfo'
+];
+
+/**
+ * 检查请求URL是否在白名单中
+ */
+function isInAuthWhitelist(url?: string): boolean {
+  if (!url) return false;
+  return AUTH_WHITELIST.some(path => url.includes(path));
+}
+
+/**
+ * 请求拦截器 - 自动添加 Authorization 头
+ */
+axiosInstance.interceptors.request.use(
+  (config) => {
+    // 检查是否在白名单中
+    if (isInAuthWhitelist(config.url)) {
+      return config;
+    }
+
+    // 从 localStorage 获取 token (浏览器环境)
+    if (typeof window !== 'undefined') {
+      const token = localStorage.getItem('access_token');
+      if (token) {
+        config.headers.Authorization = `Bearer ${token}`;
+      }
+    }
+
+    return config;
+  },
+  (error) => {
+    return Promise.reject(error);
+  }
+);
+
+/**
+ * 自定义错误类：表示需要重新登录
+ */
+export class AuthenticationError extends Error {
+  constructor(message = 'Token 已过期或无效，请重新登录') {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * 响应拦截器 - 处理 401 错误（token 过期）
+ */
+axiosInstance.interceptors.response.use(
+  (response) => {
+    return response;
+  },
+  (error) => {
+    if (isAxiosError(error) && error.response?.status === 401) {
+      // Token 过期或无效
+      console.warn('⚠️ Token 已过期或无效，请重新登录');
+
+      if (typeof window !== 'undefined') {
+        // 🌐 客户端环境：清除 localStorage 并跳转
+        localStorage.removeItem('access_token');
+        localStorage.removeItem('user_info');
+        window.location.href = '/login';
+      } else {
+        // 🖥️ 服务端环境：抛出特殊错误，由 loader/action 处理
+        console.warn('⚠️ [Server] 检测到 401 错误，抛出 AuthenticationError');
+        throw new AuthenticationError('Token 已过期或无效，请重新登录');
+      }
+    }
+
+    return Promise.reject(error);
+  }
+);
+
 // 最大重试次数
 const MAX_RETRIES = 2;
 
diff --git a/app/api/evaluation_points/reviews.ts b/app/api/evaluation_points/reviews.ts
index a247cfc..bbe9e9d 100644
--- a/app/api/evaluation_points/reviews.ts
+++ b/app/api/evaluation_points/reviews.ts
@@ -158,7 +158,8 @@ export async function  getReviewPoints(fileId: string, request: Request) {
       token: frontendJWT
     };
     const contractStructureComparisonResponse = await postgrestGet('contract_structure_comparison', contractStructureComparisonParams);
-
+    // console.log('contract_structure_comparison', contractStructureComparisonResponse)
+    
     if (contractStructureComparisonResponse.error) {
       console.error("获取文档附件数据错误:", contractStructureComparisonResponse.error);
       return Response.json({ error: contractStructureComparisonResponse.error }, { status: contractStructureComparisonResponse.status || 500 });
diff --git a/app/api/evaluation_points/rules-files.ts b/app/api/evaluation_points/rules-files.ts
index d733287..1f4a3b0 100644
--- a/app/api/evaluation_points/rules-files.ts
+++ b/app/api/evaluation_points/rules-files.ts
@@ -100,7 +100,6 @@ export interface DocumentSearchParams {
   sortOrder?: string; // 排序方式
   page?: number; // 当前页码
   pageSize?: number; // 每页条数
-  token?: string; // JWT token
 }
 
 
@@ -169,8 +168,7 @@ export async function getReviewFiles(searchParams: DocumentSearchParams = {}, do
       reviewStatus,
       dateFrom,
       dateTo,
-      sortOrder = 'upload_time_desc',
-      token
+      sortOrder = 'upload_time_desc'
     } = searchParams;
 
     let p_typeid: number[] | null = null;
@@ -206,8 +204,8 @@ export async function getReviewFiles(searchParams: DocumentSearchParams = {}, do
 
     // 并行执行获取数据和获取总数的请求
     const [filesResponse, countResponse] = await Promise.all([
-      postgrestPost<ReviewFileFromSQL[]>('rpc/get_review_files_with_details', listParams, token),
-      postgrestPost<number>('rpc/count_review_files', rpcParams, token)
+      postgrestPost<ReviewFileFromSQL[]>('rpc/get_review_files_with_details', listParams),
+      postgrestPost<number>('rpc/count_review_files', rpcParams)
     ]);
     
     // 处理获取文档列表的错误
@@ -318,10 +316,9 @@ export async function getReviewFiles(searchParams: DocumentSearchParams = {}, do
  * @param id 文件ID
  * @param auditStatus 审核状态
  * @param userId 用户ID
- * @param token JWT token (可选)
  * @returns 更新结果
  */
-export async function updateDocumentAuditStatus(id: string, auditStatus: number, userId: string, token?: string): Promise<{
+export async function updateDocumentAuditStatus(id: string, auditStatus: number, userId: string): Promise<{
   success?: boolean;
   error?: string;
   status?: number;
@@ -347,8 +344,7 @@ export async function updateDocumentAuditStatus(id: string, auditStatus: number,
       {
         id: parseInt(id),
         user_id: parseInt(userId) // 确保只能更新自己的文档
-      },
-      token
+      }
     );
 
     console.log('📝 [updateDocumentAuditStatus] postgrestPut响应:', response);
diff --git a/app/api/files/documents.ts b/app/api/files/documents.ts
index 4d6bab6..70cb7df 100644
--- a/app/api/files/documents.ts
+++ b/app/api/files/documents.ts
@@ -93,6 +93,36 @@ export interface DocumentUI {
   updatedAt?: string;
   pageCount?: number;
   ocrResult?: unknown;
+  // 版本管理相关字段
+  historyCount?: number;           // 历史版本数量（不含当前版本）
+  previousIssues?: number | null;  // 上一个版本的问题数量
+  isExpanded?: boolean;             // 是否展开历史版本（前端状态）
+  historyVersions?: DocumentVersionUI[]; // 历史版本列表
+}
+
+/**
+ * 文档历史版本结构
+ */
+export interface DocumentVersionUI {
+  id: number;
+  name: string;
+  documentNumber: string;
+  type: string;
+  typeName: string;
+  size: number;
+  auditStatus: number;
+  fileStatus: string;
+  issues: number | null;
+  issuesDiff?: number;    // 与上一个版本的问题数量差异（绝对值）
+  issuesDiffType?: 'increase' | 'decrease' | 'same'; // 差异类型
+  uploadTime: string;
+  fileType: string;
+  path: string;
+  isTest: boolean;
+  updatedAt?: string;
+  pageCount?: number;
+  ocrResult?: unknown;
+  versionNumber?: number; // 版本号（v2, v3, v4...）
 }
 
 /**
@@ -419,6 +449,8 @@ export async function getDocumentWithNoUserId(id: string, frontendJWT?: string):
     if (!id) {
       return { error: '文档ID不能为空', status: 400 };
     }
+
+    // console.log("get单个文档id", id)
     
     const response = await postgrestGet<Document[]>(
       'documents',
@@ -435,6 +467,7 @@ export async function getDocumentWithNoUserId(id: string, frontendJWT?: string):
       return { error: response.error, status: response.status };
     }
     
+    // console.log("respose", response)
     const extractedData = extractApiData<Document[]>(response.data);
     if (!extractedData || extractedData.length === 0) {
       return { error: '文档不存在', status: 404 };
@@ -554,7 +587,7 @@ export async function updateDocument(id: string, document: Partial<DocumentUI> &
     // 获取更新后的完整文档数据
     const updatedResponse = await getDocument(id, userId, frontendJWT);
     
-    return updatedResponse; 
+    return updatedResponse;
   } catch (error) {
     console.error('更新文档信息失败:', error);
     return {
@@ -562,4 +595,223 @@ export async function updateDocument(id: string, document: Partial<DocumentUI> &
       status: 500
     };
   }
+}
+
+/**
+ * 获取文档列表（带版本信息）- 使用 RPC 函数
+ * @param searchParams 搜索参数
+ * @returns 文档列表和总数
+ */
+export async function getDocumentsWithVersionInfo(searchParams: DocumentSearchParams = {}): Promise<{
+  data?: { documents: DocumentUI[], total: number };
+  error?: string;
+  status?: number;
+}> {
+  try {
+    const {
+      page = 1,
+      pageSize = 10,
+      name,
+      documentNumber,
+      documentType,
+      auditStatus,
+      fileStatus,
+      dateFrom,
+      dateTo,
+      reviewType,
+      userId,
+      token
+    } = searchParams;
+
+    // 确保userId必须存在
+    if (!userId) {
+      return { error: '用户身份验证失败，无法获取文档列表', status: 401 };
+    }
+
+    // 处理文档类型
+    let documentTypes: number[] | undefined;
+    if (documentType) {
+      documentTypes = [parseInt(documentType, 10)];
+    } else if (reviewType) {
+      if (reviewType === 'contract') {
+        documentTypes = [1];
+      } else if (reviewType === 'record') {
+        documentTypes = [2, 3, 155];
+      }
+    }
+
+    // 准备RPC调用参数
+    const rpcParams = {
+      p_user_id: parseInt(userId, 10),
+      p_page: page,
+      p_page_size: pageSize,
+      p_search_name: name || null,
+      p_search_document_number: documentNumber || null,
+      p_search_document_types: documentTypes || null,
+      p_search_audit_status: auditStatus !== undefined ? parseInt(auditStatus, 10) : null,
+      p_search_file_status: fileStatus || null,
+      p_search_date_from: dateFrom || null,
+      p_search_date_to: dateTo || null
+    };
+
+    // 并行执行获取数据和获取总数的请求
+    const [documentsResponse, countResponse] = await Promise.all([
+      postgrestPost<any[], unknown>('rpc/documents_get_latest_documents_with_version_info', rpcParams, token),
+      postgrestPost<number, unknown>('rpc/documents_count_latest_documents_with_filters', {
+        p_user_id: rpcParams.p_user_id,
+        p_search_name: rpcParams.p_search_name,
+        p_search_document_number: rpcParams.p_search_document_number,
+        p_search_document_types: rpcParams.p_search_document_types,
+        p_search_audit_status: rpcParams.p_search_audit_status,
+        p_search_file_status: rpcParams.p_search_file_status,
+        p_search_date_from: rpcParams.p_search_date_from,
+        p_search_date_to: rpcParams.p_search_date_to
+      }, token)
+    ]);
+
+    // 处理获取文档列表的错误
+    if (documentsResponse.error || !documentsResponse.data) {
+      return { error: documentsResponse.error || '获取文档数据失败', status: documentsResponse.status || 500 };
+    }
+
+    // 处理获取总数的错误
+    if (countResponse.error || typeof countResponse.data !== 'number') {
+      console.error('获取文档总数失败:', countResponse.error);
+    }
+
+    const totalCount = typeof countResponse.data === 'number' ? countResponse.data : 0;
+
+    // 将RPC返回的数据转换为UI格式
+    const documents: DocumentUI[] = documentsResponse.data.map((doc: any) => ({
+      id: doc.id,
+      name: doc.name,
+      documentNumber: doc.document_number,
+      type: doc.type_id.toString(),
+      typeName: doc.type_name || '未知类型',
+      size: doc.file_size,
+      auditStatus: doc.audit_status ?? 0,
+      fileStatus: doc.status || '',
+      issues: doc.false_count ?? null,
+      uploadTime: formatDate(doc.updated_at),
+      fileType: getFileExtension(doc.name),
+      path: doc.path,
+      isTest: doc.is_test_document,
+      updatedAt: formatDate(doc.updated_at),
+      pageCount: doc.ocr_result?.__meta?.page_count || 0,
+      ocrResult: doc.ocr_result,
+      historyCount: doc.history_count || 0,
+      previousIssues: doc.previous_issues
+    }));
+
+    return {
+      data: {
+        documents,
+        total: totalCount
+      }
+    };
+  } catch (error) {
+    console.error('获取文档列表失败:', error);
+    return {
+      error: error instanceof Error ? error.message : '获取文档列表失败',
+      status: 500
+    };
+  }
+}
+
+/**
+ * 获取文档历史版本列表
+ * @param documentName 文档名称
+ * @param userId 用户ID
+ * @param excludeId 排除的文档ID（当前最新版本的ID）
+ * @param token JWT token
+ * @returns 历史版本列表
+ */
+export async function getDocumentHistory(
+  documentName: string,
+  userId: string,
+  excludeId: number,
+  token?: string
+): Promise<{
+  data?: DocumentVersionUI[];
+  error?: string;
+  status?: number;
+}> {
+  try {
+    if (!documentName) {
+      return { error: '文档名称不能为空', status: 400 };
+    }
+
+    if (!userId) {
+      return { error: '用户身份验证失败', status: 401 };
+    }
+
+    // 调用 RPC 函数获取历史版本
+    const response = await postgrestPost<any[], unknown>(
+      'rpc/documents_get_document_history',
+      {
+        p_document_name: documentName,
+        p_user_id: parseInt(userId, 10),
+        p_exclude_id: excludeId
+      },
+      token
+    );
+
+    if (response.error || !response.data) {
+      return { error: response.error || '获取历史版本失败', status: response.status || 500 };
+    }
+
+    const historyDocs = response.data;
+
+    // 转换为 UI 格式，并计算问题数量差异
+    const documents: DocumentVersionUI[] = historyDocs.map((doc: any, index: number) => {
+      // 计算与下一个版本（更早的版本）的问题数量差异
+      let issuesDiff: number | undefined;
+      let issuesDiffType: 'increase' | 'decrease' | 'same' | undefined;
+
+      if (index < historyDocs.length - 1) {
+        const olderDoc = historyDocs[index + 1];
+        if (doc.false_count != null && olderDoc.false_count != null) {
+          const diff = doc.false_count - olderDoc.false_count;
+          issuesDiff = Math.abs(diff);
+          if (diff > 0) {
+            issuesDiffType = 'increase';
+          } else if (diff < 0) {
+            issuesDiffType = 'decrease';
+          } else {
+            issuesDiffType = 'same';
+          }
+        }
+      }
+
+      return {
+        id: doc.id,
+        name: doc.name,
+        documentNumber: doc.document_number,
+        type: doc.type_id.toString(),
+        typeName: doc.type_name || '未知类型',
+        size: doc.file_size,
+        auditStatus: doc.audit_status ?? 0,
+        fileStatus: doc.status || '',
+        issues: doc.false_count ?? null,
+        issuesDiff,
+        issuesDiffType,
+        uploadTime: formatDate(doc.created_at),
+        fileType: getFileExtension(doc.name),
+        path: doc.path,
+        isTest: doc.is_test_document,
+        updatedAt: formatDate(doc.updated_at),
+        pageCount: doc.ocr_result?.__meta?.page_count || 0,
+        ocrResult: doc.ocr_result,
+        versionNumber: historyDocs.length - index 
+      };
+    });
+
+    return { data: documents };
+  } catch (error) {
+    console.error('获取文档历史版本失败:', error);
+    return {
+      error: error instanceof Error ? error.message : '获取文档历史版本失败',
+      status: 500
+    };
+  }
 }
\ No newline at end of file
diff --git a/app/api/files/files-upload.ts b/app/api/files/files-upload.ts
index 8b36025..b91e68d 100644
--- a/app/api/files/files-upload.ts
+++ b/app/api/files/files-upload.ts
@@ -175,9 +175,13 @@ export async function uploadContractTemplate(
     const headers: HeadersInit = {
       'Accept': 'application/json'
     };
-    
-    if (jwtToken) {
-      headers['Authorization'] = `Bearer ${jwtToken}`;
+
+    // 从 localStorage 获取 token
+    if (typeof window !== 'undefined') {
+      const token = localStorage.getItem('access_token');
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
     }
     
     // 发送请求
@@ -222,7 +226,6 @@ export async function uploadContractTemplate(
  * @param mergeMode 合并模式：'overwrite'（覆盖原文档）或 'new'（新建文档记录）
  * @param isReprocess 是否触发重新处理
  * @param remark 备注
- * @param jwtToken JWT token
  * @returns 上传结果
  */
 export async function appendContractAttachments(
@@ -230,8 +233,7 @@ export async function appendContractAttachments(
   files: File[],
   mergeMode: 'overwrite' | 'new' = 'overwrite',
   isReprocess: boolean = true,
-  remark?: string,
-  jwtToken?: string
+  remark?: string
 ): Promise<{data: FileUploadResponse; error?: never} | {data?: never; error: string; status?: number}> {
   try {
     console.log('【合同附件追加】开始追加附件:', { documentId, fileCount: files.length, mergeMode });
@@ -259,9 +261,13 @@ export async function appendContractAttachments(
     const headers: HeadersInit = {
       'Accept': 'application/json'
     };
-    
-    if (jwtToken) {
-      headers['Authorization'] = `Bearer ${jwtToken}`;
+
+    // 从 localStorage 获取 token
+    if (typeof window !== 'undefined') {
+      const token = localStorage.getItem('access_token');
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
     }
     
     // 发送请求
diff --git a/app/api/home/home.ts b/app/api/home/home.ts
index e04daea..88e4851 100644
--- a/app/api/home/home.ts
+++ b/app/api/home/home.ts
@@ -436,72 +436,7 @@ export async function getHomeData(reviewType?: string | null,userId?: string | n
           lastMonthIssuesCount = lastMonthType2Count
           
         }
-        // 暂时不会存在没有指定类型得情况，暂不实现。
-        //  else {
-        //   // 如果没有指定类型，则使用原来的查询方式获取所有类型的问题数量
-        //   const thisMonthIssuesParams: PostgrestParams = {
-        //     select: 'count',
-        //     filter: {
-        //       and: `(created_at.gte.${startOfThisMonth},created_at.lte.${endOfThisMonth})`,
-        //       'evaluated_results->result': 'eq.false',
-        //       user_id: `eq.${userId}`
-        //     }
-        //   };
-          
-        //   // 添加类型过滤条件
-        //   if (typeFilter) {
-        //     if (typeFilter.startsWith('(')) {
-        //       thisMonthIssuesParams.or = typeFilter;
-        //     } else {
-        //       const [field, op, value] = typeFilter.split('.');
-        //       if (!thisMonthIssuesParams.filter) {
-        //         thisMonthIssuesParams.filter = {};
-        //       }
-        //       thisMonthIssuesParams.filter[field] = `${op}.${value}`;
-        //     }
-        //   }
-          
-        //   const thisMonthIssuesResponse = await handleApiResponse<{ count: number }[]>(
-        //     postgrestGet('evaluation_results', thisMonthIssuesParams),
-        //     '获取本月问题数据失败',
-        //     []
-        //   );
-          
-        //   // 本月问题数量
-        //   thisMonthIssuesCount = thisMonthIssuesResponse[0]?.count || 0;
-          
-        //   // 上月问题数量
-        //   const lastMonthIssuesParams: PostgrestParams = {
-        //     select: 'count',
-        //     filter: {
-        //       and: `(created_at.gte.${startOfLastMonth},created_at.lte.${endOfLastMonth})`,
-        //       'evaluated_results->result': 'eq.false',
-        //       user_id: `eq.${userId}`
-        //     }
-        //   };
-          
-        //   // 添加类型过滤条件
-        //   if (typeFilter) {
-        //     if (typeFilter.startsWith('(')) {
-        //       lastMonthIssuesParams.or = typeFilter;
-        //     } else {
-        //       const [field, op, value] = typeFilter.split('.');
-        //       if (!lastMonthIssuesParams.filter) {
-        //         lastMonthIssuesParams.filter = {};
-        //       }
-        //       lastMonthIssuesParams.filter[field] = `${op}.${value}`;
-        //     }
-        //   }
-          
-        //   const lastMonthIssuesResponse = await handleApiResponse<{ count: number }[]>(
-        //     postgrestGet('evaluation_results', lastMonthIssuesParams),
-        //     '获取上月问题数据失败',
-        //     []
-        //   );
-          
-        //   // 上月问题数量
-        //   lastMonthIssuesCount = lastMonthIssuesResponse[0]?.count || 0;
-        // }
+
 
         // 计算问题数量同比增长
         let issuesGrowthValue = 0;
diff --git a/app/api/login/auth.server.ts b/app/api/login/auth.server.ts
index b8b07d6..91ab66e 100644
--- a/app/api/login/auth.server.ts
+++ b/app/api/login/auth.server.ts
@@ -30,7 +30,7 @@ import { OAUTH_CONFIG, API_BASE_URL } from "~/config/api-config";
  * @property {'common'} common - 普通用户，有基本的系统访问权限
  * @property {'developer'} developer - 开发者/管理员，有完整的系统管理权限
  */
-export type UserRole = 'common' | 'admin' | 'deptLeader' | 'groupLeader';
+export type UserRole = 'common' | 'admin' | 'deptLeader' | 'groupLeader' | string;
 
 /**
  * 用户信息接口，对应 sso_users 表结构
@@ -365,7 +365,7 @@ export async function getUserSession(request: Request) {
  */
 export async function createUserSession(params: {
   isAuthenticated: boolean;
-  userRole: UserRole;
+  userRole: string;
   redirectTo: string;
   accessToken?: string;
   refreshToken?: string;
diff --git a/app/api/login/login-client.ts b/app/api/login/login-client.ts
new file mode 100644
index 0000000..fa5bc82
--- /dev/null
+++ b/app/api/login/login-client.ts
@@ -0,0 +1,154 @@
+/**
+ * 登录客户端
+ * 调用后端 /auth/login 接口,传递 OAuth 用户信息,获取 JWT token
+ */
+
+import { API_BASE_URL } from "~/config/api-config";
+
+/**
+ * 登录请求参数（OAuth 方式）
+ */
+export interface LoginRequest {
+  userInfo: {
+    sub: string;
+    username?: string;
+    nickname?: string;
+    email?: string;
+    phone_number?: string;
+    ou_id?: string;
+    ou_name?: string;
+    is_leader?: boolean;
+    [key: string]: unknown;
+  };
+  expiresIn: number;
+  area?: string;
+}
+
+/**
+ * 登录响应
+ */
+export interface LoginResponse {
+  success: boolean;
+  data?: {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    user_info: {
+      user_id: string;
+      username: string;
+      nick_name: string;
+      email?: string;
+      phone_number?: string;
+      ou_id: string;
+      ou_name: string;
+      is_leader: boolean;
+      user_role: string;
+      sub: string;
+    };
+  };
+  error?: string;
+  message?: string;
+}
+
+/**
+ * 调用后端登录接口（OAuth 方式）
+ *
+ * @param loginData 登录数据（OAuth 用户信息）
+ * @returns 登录响应（包含 JWT token）
+ */
+export async function loginWithOAuth(loginData: LoginRequest): Promise<LoginResponse> {
+  const loginUrl = `${API_BASE_URL}/auth/login`;
+
+  console.log("📝 [Login Client] 调用后端 OAuth 登录接口:", loginUrl);
+
+  try {
+    const response = await fetch(loginUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify(loginData)
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      console.error("❌ [Login Client] OAuth 登录请求失败:", response.status, errorData);
+
+      return {
+        success: false,
+        error: errorData.error || errorData.message || `登录失败: ${response.status}`
+      };
+    }
+
+    const data = await response.json();
+    console.log("✅ [Login Client] OAuth 登录成功");
+
+    return data;
+  } catch (error) {
+    console.error("❌ [Login Client] OAuth 登录请求异常:", error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "网络请求失败"
+    };
+  }
+}
+
+/**
+ * 密码登录请求参数
+ */
+export interface PasswordLoginRequest {
+  username: string;
+  password: string;
+}
+
+/**
+ * 调用后端登录接口（密码方式）
+ *
+ * @param username 用户名
+ * @param password 密码
+ * @returns 登录响应（包含 JWT token）
+ */
+export async function loginWithPassword(
+  username: string,
+  password: string
+): Promise<LoginResponse> {
+  const loginUrl = `${API_BASE_URL}/auth/login`;
+
+  console.log("📝 [Login Client] 调用后端密码登录接口:", loginUrl);
+
+  try {
+    const response = await fetch(loginUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({
+        username,
+        password
+      })
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      console.error("❌ [Login Client] 密码登录请求失败:", response.status, errorData);
+
+      return {
+        success: false,
+        error: errorData.error || errorData.message || `登录失败: ${response.status}`
+      };
+    }
+
+    const data = await response.json();
+    console.log("✅ [Login Client] 密码登录成功");
+
+    return data;
+  } catch (error) {
+    console.error("❌ [Login Client] 密码登录请求异常:", error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "网络请求失败"
+    };
+  }
+}
diff --git a/app/api/postgrest-client.ts b/app/api/postgrest-client.ts
index 5ee6eba..09b5be2 100644
--- a/app/api/postgrest-client.ts
+++ b/app/api/postgrest-client.ts
@@ -106,11 +106,11 @@ function mergeAuthHeaders(
     return headers;
   }
   
-  // 优先使用显式传入的 token，否则从上下文获取
-  const token = explicitToken || 'undefined';
-  
-  // 如果有 token（显式传入或从上下文获取），添加到 Authorization 头部
-  if (token) {
+  // 优先使用显式传入的 token，否则尝试从客户端 localStorage 获取
+  const token = explicitToken || (typeof window !== 'undefined' ? localStorage.getItem('access_token') : undefined);
+
+  // 如果有有效的 token（显式传入或从客户端获取），添加到 Authorization 头部
+  if (token && token !== 'undefined') {
     headers['Authorization'] = `Bearer ${token}`;
   }
   
diff --git a/app/components/auth/ClientAuthGuard.tsx b/app/components/auth/ClientAuthGuard.tsx
new file mode 100644
index 0000000..cd5e499
--- /dev/null
+++ b/app/components/auth/ClientAuthGuard.tsx
@@ -0,0 +1,57 @@
+/**
+ * 客户端认证守卫组件
+ *
+ * 在客户端检查 localStorage 中的 token
+ * 如果未认证且访问的是需要认证的路径，则跳转到登录页
+ */
+
+import { useEffect } from 'react';
+import { useNavigate, useLocation } from '@remix-run/react';
+import { isAuthenticated } from '~/utils/auth-storage';
+
+interface ClientAuthGuardProps {
+  isPublicPath: boolean;
+}
+
+export function ClientAuthGuard({ isPublicPath }: ClientAuthGuardProps) {
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  useEffect(() => {
+    console.log('🔍 [Auth Guard] useEffect 触发', {
+      isPublicPath,
+      pathname: location.pathname
+    });
+
+    // 如果是公共路径，不需要检查认证
+    if (isPublicPath) {
+      console.log('✅ [Auth Guard] 公共路径，跳过认证检查');
+      return;
+    }
+
+    // 检查客户端是否已认证（localStorage 中有 token）
+    const token = localStorage.getItem('access_token');
+    const authenticated = isAuthenticated();
+
+    console.log('🔍 [Auth Guard] 认证检查', {
+      token: token ? `${token.substring(0, 20)}...` : null,
+      authenticated,
+      pathname: location.pathname
+    });
+
+    if (!authenticated) {
+      console.log('🔒 [Auth Guard] 未认证，重定向到登录页');
+
+      // 保存当前路径，登录后可以跳转回来
+      const redirectTo = location.pathname !== '/login' ? location.pathname : '/';
+
+      // 跳转到登录页，并传递重定向目标
+      navigate(`/login?redirect=${encodeURIComponent(redirectTo)}`, { replace: true });
+    } else {
+      console.log('✅ [Auth Guard] 已认证，允许访问');
+    }
+  }, [isPublicPath, navigate, location.pathname]);
+
+  // 这个组件不渲染任何内容
+  return null;
+}
diff --git a/app/components/layout/Layout.tsx b/app/components/layout/Layout.tsx
index 93ca52c..afe5d7f 100644
--- a/app/components/layout/Layout.tsx
+++ b/app/components/layout/Layout.tsx
@@ -36,6 +36,8 @@ interface Match {
 export function Layout({ children, userRole = 'developer' as UserRole, frontendJWT = '' }: LayoutProps) {
   const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
   const [selectedApp, setSelectedApp] = useState<AppModule>('');
+  const [effectiveUserRole, setEffectiveUserRole] = useState<UserRole>(userRole);
+  const [effectiveFrontendJWT, setEffectiveFrontendJWT] = useState<string>(frontendJWT);
   const matches = useMatches() as Match[];
   const location = useLocation();
 
@@ -48,6 +50,39 @@ export function Layout({ children, userRole = 'developer' as UserRole, frontendJ
     match.handle && match.handle.hideBreadcrumb === true
   );
 
+  // 从 localStorage 读取用户信息和 JWT 作为备用方案
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    try {
+      // 如果服务端没有传递 userRole，从 localStorage 读取
+      if (!userRole || userRole === '') {
+        const storedUserInfoStr = localStorage.getItem('user_info');
+        if (storedUserInfoStr) {
+          const storedUserInfo = JSON.parse(storedUserInfoStr);
+          const storedUserRole = storedUserInfo.user_role || 'common';
+          console.log('📖 [Layout] 从 localStorage 读取用户角色:', storedUserRole);
+          setEffectiveUserRole(storedUserRole as UserRole);
+        }
+      } else {
+        setEffectiveUserRole(userRole);
+      }
+
+      // 如果服务端没有传递 frontendJWT，从 localStorage 读取
+      if (!frontendJWT || frontendJWT === '') {
+        const storedToken = localStorage.getItem('access_token');
+        if (storedToken) {
+          console.log('📖 [Layout] 从 localStorage 读取 JWT token');
+          setEffectiveFrontendJWT(storedToken);
+        }
+      } else {
+        setEffectiveFrontendJWT(frontendJWT);
+      }
+    } catch (error) {
+      console.error('❌ [Layout] 读取 localStorage 失败:', error);
+    }
+  }, [userRole, frontendJWT]);
+
   // 从sessionStorage中获取侧边栏状态和reviewType
   useEffect(() => {
     // 检查是否为移动端
@@ -62,7 +97,7 @@ export function Layout({ children, userRole = 'developer' as UserRole, frontendJ
     } else if (savedState) {
       setSidebarCollapsed(savedState === 'true');
     }
-    
+
     // 从sessionStorage获取reviewType并设置对应的应用模块
     if (typeof window !== 'undefined') {
       try {
@@ -111,12 +146,12 @@ export function Layout({ children, userRole = 'developer' as UserRole, frontendJ
   return (
     <div className="layout-container">
       {/* 侧边栏始终保留，不再使用条件渲染 */}
-      <Sidebar 
-        collapsed={sidebarCollapsed} 
-        onToggle={toggleSidebar} 
-        userRole={userRole}
+      <Sidebar
+        collapsed={sidebarCollapsed}
+        onToggle={toggleSidebar}
+        userRole={effectiveUserRole}
         selectedApp={selectedApp}
-        frontendJWT={frontendJWT}
+        frontendJWT={effectiveFrontendJWT}
       />
       
       <div className={`main-content ${sidebarCollapsed ? 'sidebar-collapsed' : ''}`}>
diff --git a/app/components/layout/Sidebar.tsx b/app/components/layout/Sidebar.tsx
index 79f4e04..7f879d2 100644
--- a/app/components/layout/Sidebar.tsx
+++ b/app/components/layout/Sidebar.tsx
@@ -11,11 +11,28 @@ interface SidebarProps {
   selectedApp?: string; // 添加所选应用模块参数
 }
 
-// 定义不同应用模块下显示的菜单项ID
+// 定义不同应用模块下显示的菜单路径（使用路由路径进行匹配）
 const APP_MENU_MAP = {
-  'contract': ['home', 'contract-template', 'file-management', 'rule-management', 'cross-checking', 'system-settings'],
-  'record': ['home', 'file-management', 'rule-management', 'cross-checking', 'system-settings'],
-  'model': ['chat-with-llm']
+  'contract': [
+    '/home',              // 系统概览
+    '/documents',         // 文档管理
+    '/contract-template', // 合同模板
+    '/rules',            // 评查规则库
+    '/cross-checking',    // 交叉评查
+    // '/chat-with-llm',     // AI法务助手
+    '/settings'           // 系统设置
+  ],
+  'record': [
+    '/home',              // 系统概览
+    '/documents',         // 文档管理
+    '/rules',            // 评查规则库
+    '/cross-checking',    // 交叉评查
+    // '/chat-with-llm',     // AI法务助手
+    '/settings'           // 系统设置
+  ],
+  'model': [
+    '/chat-with-llm'      // AI法务助手
+  ]
 };
 
 // 应用模块名称映射
@@ -62,28 +79,43 @@ export function Sidebar({ onToggle, collapsed, userRole, frontendJWT = '', selec
     const fetchUserRoutes = async () => {
       setIsLoadingRoutes(true);
       try {
-        console.log('userRole', userRole);
+        // 优先使用传入的 frontendJWT，否则从 localStorage 读取
+        let jwt = frontendJWT;
+
+        if (!jwt && typeof window !== 'undefined') {
+          jwt = localStorage.getItem('access_token') || '';
+          console.log('📖 [Sidebar] 从 localStorage 读取 JWT');
+        }
+
+        if (!jwt) {
+          console.error('❌ [Sidebar] JWT token 未找到');
+          setMenuItems([]);
+          setIsLoadingRoutes(false);
+          return;
+        }
+
+        console.log('🔍 [Sidebar] 当前用户角色:', userRole);
         const roleKey = mapUserRoleToRoleKey(userRole);
-        const result = await getUserRoutesByRole(roleKey, frontendJWT);
-        
+        const result = await getUserRoutesByRole(roleKey, jwt);
+
         if (result.success && result.data) {
           setMenuItems(result.data);
-          console.log('用户路由权限加载成功:', result.data);
+          console.log('✅ [Sidebar] 用户路由权限加载成功:', result.data);
         } else {
-          console.error('获取用户路由权限失败:', result.error);
-          
+          console.error('❌ [Sidebar] 获取用户路由权限失败:', result.error);
+
           // 如果需要重定向到首页
           if (result.shouldRedirectToHome) {
-            console.log('重定向到首页');
+            console.log('🔄 [Sidebar] 重定向到首页');
             navigate('/');
             return;
           }
-          
+
           // 其他错误情况，使用空数组
           setMenuItems([]);
         }
       } catch (error) {
-        console.error('获取用户路由权限时发生错误:', error);
+        console.error('❌ [Sidebar] 获取用户路由权限时发生错误:', error);
         // 发生异常时也重定向到首页
         navigate('/');
         return;
@@ -93,7 +125,7 @@ export function Sidebar({ onToggle, collapsed, userRole, frontendJWT = '', selec
     };
 
     fetchUserRoutes();
-  }, [userRole, navigate]);
+  }, [userRole, frontendJWT, navigate]);
 
   // 组件挂载后从 sessionStorage 读取初始 reviewType
   useEffect(() => {
@@ -225,37 +257,60 @@ export function Sidebar({ onToggle, collapsed, userRole, frontendJWT = '', selec
     // console.log('子菜单点击:', child.title, '路径:', child.path);
   };
 
-  // 获取当前应用模式下应显示的菜单ID列表
-  const visibleMenuIds = APP_MENU_MAP[currentApp as keyof typeof APP_MENU_MAP] || APP_MENU_MAP['contract'];
-  // const visibleMenuIds = APP_MENU_MAP[currentApp as keyof typeof APP_MENU_MAP]
-  // console.log('当前应用模式:', currentApp, '可见菜单ID:', visibleMenuIds);
+  // 获取当前应用模式下应显示的菜单路径列表
+  const visibleMenuPaths = APP_MENU_MAP[currentApp as keyof typeof APP_MENU_MAP] || APP_MENU_MAP['contract'];
+  // console.log('当前应用模式:', currentApp, '可见菜单路径:', visibleMenuPaths);
 
   // 检查是否通过51707端口访问（省局）
   // const isPort51708 = typeof window !== 'undefined' && window.location.port === '51708';
   const isPort51707 = typeof window !== 'undefined' && window.location.port === '51707';
 
   // 根据当前应用模式过滤菜单项
-  const filteredMenuItems = menuItems.filter(item => {
-    // 如果是51707端口，只显示交叉评查相关菜单
-    if (isPort51707) {
-      // 如果当前应用是智慧法务大模型，只显示AI对话菜单
-      if (currentApp === 'model') {
-        return item.id === 'chat-with-llm' || 
-              (item.path && item.path.startsWith('/chat-with-llm'));
-      }else{
-        return item.id === 'cross-checking' || 
-               (item.path && item.path.startsWith('/cross-checking'))
+  const filteredMenuItems = menuItems
+    .filter(item => {
+      // 如果是51707端口，只显示交叉评查相关菜单
+      if (isPort51707) {
+        // 如果当前应用是智慧法务大模型，只显示AI对话菜单
+        if (currentApp === 'model') {
+          return item.path && item.path.startsWith('/chat-with-llm');
+        } else {
+          return item.path && item.path.startsWith('/cross-checking');
+        }
       }
-    }
 
+      // 检查当前菜单是否在所选应用模式中显示（使用路径匹配）
+      if (!visibleMenuPaths.includes(item.path)) {
+        return false;
+      }
 
-    // 检查当前菜单是否在所选应用模式中显示
-    if (!visibleMenuIds.includes(item.id)) {
-      return false;
-    }
+      return true;
+    })
+    .map(item => {
+      // 处理子菜单：过滤隐藏的子菜单
+      if (item.children && item.children.length > 0) {
+        // 过滤掉 hideBreadcrumb=true 的子菜单（这些通常是隐藏菜单）
+        const visibleChildren = item.children.filter(child => !child.hideBreadcrumb);
 
-    return true;
-  });
+        // 如果过滤后没有可见的子菜单，返回不带子菜单的父级（变成可点击的单级菜单）
+        if (visibleChildren.length === 0) {
+          const { children, ...itemWithoutChildren } = item;
+          return itemWithoutChildren;
+        }
+
+        // 如果还有可见的子菜单，返回带过滤后子菜单的项
+        return { ...item, children: visibleChildren };
+      }
+
+      // 处理空 children 数组或 undefined 的情况
+      if (item.children !== undefined) {
+        // 如果 children 存在但为空数组，移除它（让父级变成可点击的单级菜单）
+        const { children, ...itemWithoutChildren } = item;
+        return itemWithoutChildren;
+      }
+
+      // 没有子菜单的项直接返回
+      return item;
+    });
 
   // filteredMenuItems = filteredMenuItems.map(item => {
   //   if(item.children && item.children.length > 0){
diff --git a/app/components/reviews/ReviewTabs.tsx b/app/components/reviews/ReviewTabs.tsx
index f9e46ef..0b8553d 100644
--- a/app/components/reviews/ReviewTabs.tsx
+++ b/app/components/reviews/ReviewTabs.tsx
@@ -49,7 +49,7 @@ export function ReviewTabs({ activeTab, onTabChange, children, fileInfo, onConfi
     // 根据来源页面返回
     const previousRoute = fileInfo.previousRoute || 'documents';
     const returnTo = previousRoute === 'documents'
-      ? "/documents"
+      ? "/documents/list"
       : previousRoute === 'filesUpload'
         ? "/files/upload"
         : "/rules-files";
diff --git a/app/components/ui/IssuesDiff.tsx b/app/components/ui/IssuesDiff.tsx
new file mode 100644
index 0000000..b7b43a8
--- /dev/null
+++ b/app/components/ui/IssuesDiff.tsx
@@ -0,0 +1,59 @@
+/**
+ * 问题数量差异显示组件
+ * 用于显示文档版本之间的问题数量对比
+ */
+
+interface IssuesDiffProps {
+  currentIssues: number | null;
+  previousIssues?: number | null;
+  issuesDiff?: number;
+  issuesDiffType?: 'increase' | 'decrease' | 'same';
+  className?: string;
+}
+
+export function IssuesDiff({
+  currentIssues,
+  previousIssues,
+  issuesDiff,
+  issuesDiffType,
+  className = ''
+}: IssuesDiffProps) {
+  // 如果当前问题数量为 null，显示 "-"
+  if (currentIssues === null) {
+    return <span className={`issues-number ${className}`}>-</span>;
+  }
+
+  // 如果没有上一个版本或上一个版本问题数量为 null，只显示当前数量
+  if (previousIssues === null || previousIssues === undefined || issuesDiffType === undefined) {
+    return <span className={`issues-number ${className}`}>{currentIssues}</span>;
+  }
+
+  // 显示当前数量 + 差异
+  return (
+    <div className={`issues-count-wrapper ${className}`}>
+      <span className="issues-number">{currentIssues}</span>
+      {issuesDiff !== undefined && issuesDiffType && (
+        <span className={`issues-diff ${issuesDiffType}`}>
+          {issuesDiffType === 'increase' && (
+            <>
+              <i className="ri-arrow-up-line"></i>
+              <span>+{issuesDiff}</span>
+            </>
+          )}
+          {issuesDiffType === 'decrease' && (
+            <>
+              <i className="ri-arrow-down-line"></i>
+              <span>-{issuesDiff}</span>
+            </>
+          )}
+          {issuesDiffType === 'same' && (
+            <>
+              <i className="ri-subtract-line"></i>
+              <span>0</span>
+            </>
+          )}
+        </span>
+      )}
+    </div>
+  );
+}
diff --git a/app/components/ui/MultiCascader.tsx b/app/components/ui/MultiCascader.tsx
index 9d57164..e5ff701 100644
--- a/app/components/ui/MultiCascader.tsx
+++ b/app/components/ui/MultiCascader.tsx
@@ -113,19 +113,24 @@ const MultiCascader: React.FC<MultiCascaderProps> = ({
         <div className="flex items-center py-1">
           <input
             type="checkbox"
-            className="form-checkbox h-4 w-4 text-[var(--color-primary,#00684a)] rounded border-gray-300 focus:ring-[var(--color-primary,#00684a)]"
+            className="h-4 w-4 rounded border-gray-300"
+            style={{
+              accentColor: '#00684a', // 固定为绿色（烟草企业绿）
+              cursor: 'pointer'
+            }}
             checked={allChecked}
             ref={el => { if (el) el.indeterminate = !allChecked && someChecked; }}
             onChange={e => handleItemCheck(option, e.target.checked)}
             id={`cascader-${option.value}`}
           />
-          <label htmlFor={`cascader-${option.value}`} className="ml-2 text-sm flex-1">
+          <label htmlFor={`cascader-${option.value}`} className="ml-2 text-sm flex-1 cursor-pointer">
             {option.label}
           </label>
           {hasChildren && (
             <button
               type="button"
-              className="ml-2 text-gray-400 hover:text-gray-600"
+              className="ml-2"
+              style={{ color: 'gray' }} // 展开图标固定为绿色
               onClick={(e) => {
                 e.stopPropagation();
                 toggleExpand(option.value);
diff --git a/app/components/ui/index.ts b/app/components/ui/index.ts
index fa665da..118f56c 100644
--- a/app/components/ui/index.ts
+++ b/app/components/ui/index.ts
@@ -29,7 +29,4 @@ export { MessageModal } from './MessageModal';
 export { LoadingBar } from './LoadingBar';
 export { RouteChangeLoader } from './RouteChangeLoader';
 export { FileProgress } from './FileProgress';
-export { ProcessingSteps } from './ProcessingSteps';
-
-// 示例组件（开发环境使用）
-export { TooltipExample } from '../../routes/examples/TooltipExample'; 
\ No newline at end of file
+export { ProcessingSteps } from './ProcessingSteps'; 
\ No newline at end of file
diff --git a/app/root.tsx b/app/root.tsx
index 133b11f..63bcafc 100644
--- a/app/root.tsx
+++ b/app/root.tsx
@@ -20,6 +20,8 @@ import { Layout } from "~/components/layout/Layout";
 import { ErrorBoundary as AppErrorBoundary } from "~/components/error/ErrorBoundary";
 import { MessageModalProvider } from "~/components/ui/MessageModal";
 import { ToastProvider } from "~/components/ui/Toast";
+import { ClientAuthGuard } from "~/components/auth/ClientAuthGuard";
+import { getAccessToken } from "./utils/auth-storage";
 import "remixicon/fonts/remixicon.css";
 // 导入样式
 import styles from "~/styles/main.css?url";
@@ -32,25 +34,66 @@ import RouteChangeLoader from "~/components/ui/RouteChangeLoader";
 
 // 导入认证相关的服务器端功能（仅在服务器端使用）
 import { 
-  getUserSession, 
-  getSession,
-  sessionStorage,
+  // getUserSession, 
   logout,
   type UserRole 
 } from "~/api/login/auth.server";
 
 // 定义需要高级权限的路径
-export const developerOnlyPaths = [
-  '/settings',
-  '/config-lists',
-  '/document-types',
-  '/prompts',
-];
+// export const developerOnlyPaths = [
+//   '/settings',
+//   '/config-lists',
+//   '/document-types',
+//   '/prompts',
+// ];
 
 // 导出类型供客户端使用
 export type { UserRole };
 
+// 辅助函数：从 MenuItem 数组中提取所有路径（包括子路由）
+interface MenuItem {
+  path: string;
+  children?: MenuItem[];
+}
 
+function extractAllPaths(menuItems: MenuItem[]): string[] {
+  const paths: string[] = [];
+
+  function traverse(items: MenuItem[]) {
+    for (const item of items) {
+      paths.push(item.path);
+      if (item.children && item.children.length > 0) {
+        traverse(item.children);
+      }
+    }
+  }
+
+  traverse(menuItems);
+  return paths;
+}
+
+// 辅助函数：检查路径是否在允许列表中
+function isPathAllowed(pathname: string, allowedPaths: string[]): boolean {
+  // 精确匹配
+  if (allowedPaths.includes(pathname)) {
+    return true;
+  }
+
+  // 前缀匹配（处理动态路由和子路由）
+  // 例如：allowedPaths 包含 '/documents'，则 '/documents/123' 也应该被允许
+  for (const allowedPath of allowedPaths) {
+    if (pathname.startsWith(allowedPath + '/')) {
+      return true;
+    }
+  }
+
+  // 根路径特殊处理
+  if (pathname === '/' || pathname === '/home') {
+    return true; // 首页通常对所有已登录用户开放
+  }
+
+  return false;
+}
 
 // 添加action处理登录/登出请求
 export async function action({ request }: ActionFunctionArgs) {
@@ -70,89 +113,98 @@ export async function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url);
   const pathname = url.pathname;
 
-  // 排除不需要登录验证的路径
+  // 排除不需要登录验证的路径（公共路径）
   const publicPaths = ['/login', '/favicon.ico', '/callback'];
   const isPublicPath = publicPaths.some(path => pathname.startsWith(path));
 
-  // 获取用户会话（可能包含刷新后的token）
-  const { isAuthenticated, userRole, refreshedSession, frontendJWT } = await getUserSession(request);
-  // console.log("是否公开路径:", isPublicPath, "是否已认证:", isAuthenticated);
+  // 获取用户角色和 JWT（从 Cookie Session）
+  let userRole: UserRole = 'common'; // 默认为普通用户
+  let frontendJWT: string | null = null;
+  let allowedPaths: string[] = []; // 用户允许访问的路由列表
 
-  // 如果访问需要认证的路径但未登录，重定向到登录页
-  if (!isPublicPath && !isAuthenticated) {
-    console.log("未认证，需要重定向到登录页");
-    // 保存请求的URL，以便登录后重定向回来
-    const session = await getSession(request);
+  if (!isPublicPath) {
+    try {
+      const { getUserSession } = await import("~/api/login/auth.server");
+      const session = await getUserSession(request);
+      userRole = session.userRole || 'common';
+      frontendJWT = session.frontendJWT || null;
+      // console.log("🔑 [Root Loader] 用户角色:", userRole);
 
-    // 如果路径是/home，则将重定向目标设置为/
-    const redirectTarget = pathname !== "/" ? "/" : pathname;
-    // const redirectTarget = pathname === "home" ? "/" : pathname;
-    // 保存重定向目标
-    session.set("redirectTo", redirectTarget);
+      // 🔒 RBAC 路由权限检查
+      if (frontendJWT) {
+        const { getUserRoutesByRole } = await import("~/api/auth/user-routes");
+        const routesResult = await getUserRoutesByRole(userRole, frontendJWT);
 
-    return redirect("/login", {
-      headers: {
-        "Set-Cookie": await sessionStorage.commitSession(session),
-      },
-    });
+        if (routesResult.success && routesResult.data) {
+          // 从菜单数据中提取所有允许的路径
+          allowedPaths = extractAllPaths(routesResult.data);
+          // console.log("🔑 [Root Loader] 用户允许的路由:", allowedPaths);
+
+          // 检查当前路径是否在允许列表中
+          const isAllowedPath = isPathAllowed(pathname, allowedPaths);
+
+          if (!isAllowedPath) {
+            console.warn(`⚠️ [Root Loader] 用户尝试访问未授权路由: ${pathname}`);
+            // 返回 403 错误，而不是 redirect（避免循环）
+            throw new Response("无权访问此页面", { status: 403 });
+          }
+        } else {
+          // 获取路由权限失败，只记录警告，不阻止访问（避免影响正常使用）
+          console.warn("⚠️ [Root Loader] 获取用户路由权限失败，跳过权限检查");
+        }
+      }
+    } catch (error) {
+      // 如果是 Response 对象（403 错误），直接抛出
+      if (error instanceof Response) {
+        throw error;
+      }
+
+      // 🔑 检查是否是 AuthenticationError（token 过期）
+      if (error instanceof Error && error.name === 'AuthenticationError') {
+        console.warn("⚠️ [Root Loader] Token 过期，重定向到登录页");
+        // 保存当前路径，登录后可以跳转回来
+        const redirectTo = pathname !== '/login' ? pathname : '/';
+        return redirect(`/login?redirect=${encodeURIComponent(redirectTo)}`);
+      }
+
+      console.warn("⚠️ [Root Loader] 获取用户会话失败:", error);
+      // 保持默认值 'common'
+    }
   }
 
-  // 如果已登录且访问登录页，重定向到首页
-  if (pathname === "/login" && isAuthenticated) {
-    console.log("已认证，重定向到首页");
-    return redirect("/");
-  }
+  // ⚠️ 重要：现在使用客户端 localStorage 存储 token，服务端不再检查 session
+  // 认证检查改为在客户端进行（通过 ClientAuthGuard 组件）
 
-  // 检查访问权限 - 如果是common用户访问了开发者专属页面，重定向到首页
-  if (userRole === 'common' && developerOnlyPaths.some(path => pathname.startsWith(path))) {
-    console.log("用户没有访问权限，重定向到首页");
-    return redirect("/");
+  if (!frontendJWT) {
+    frontendJWT = getAccessToken();
   }
 
   // 检查51707端口访问控制
-  
-  // 由于应用直接运行在51707端口，我们需要从环境变量或运行时获取端口
   const currentPort = process.env.PORT || process.env.API_PORT_CONFIG;
-  // console.log("currentPort-----------",currentPort)
-  
-  // 获取运行时端口（从请求URL或环境变量）
   const runtimePort = url.port || currentPort;
-  // console.log("runtimePort-----------",runtimePort)
-
   const isPort51707 = currentPort === '51707' || runtimePort === '51707';
-  
+
   if (isPort51707 && !isPublicPath) {
     // 51707端口(省局)只允许访问交叉评查相关路径和首页
     const allowedPaths = ['/', '/cross-checking','/chat-with-llm'];
-    const isAllowedPath = allowedPaths.some(path => pathname === path) || 
+    const isAllowedPath = allowedPaths.some(path => pathname === path) ||
                          pathname.startsWith('/cross-checking/') ||
                          pathname.startsWith('/chat-with-llm/');
-    
+
     if (!isAllowedPath) {
-      // console.log("51707端口访问受限，重定向到交叉评查页面");
       return redirect("/cross-checking");
     }
   }
 
-  // 如果token被刷新了，需要在响应中设置更新后的cookie
-  const responseHeaders: Record<string, string> = {};
-  if (refreshedSession) {
-    responseHeaders["Set-Cookie"] = await sessionStorage.commitSession(refreshedSession);
-  }
-
-  // 向组件传递认证状态、当前路径
-  // 注意：不再传递 Dify 相关环境变量，客户端改为调用 Remix API routes
+  // 向组件传递路径信息
   return Response.json({
-    isAuthenticated,
-    userRole,
+    userRole,  // ✅ 返回真实的用户角色
     pathname,
     frontendJWT,
+    isPublicPath,  // 传递给客户端，用于判断是否需要认证
     ENV: {
-      // 移除 NEXT_PUBLIC_API_URL, NEXT_PUBLIC_APP_ID, NEXT_PUBLIC_APP_KEY
       // 客户端不再需要直接调用 Dify API
     },
-  }, {
-    headers: responseHeaders
   });
 }
 
@@ -183,7 +235,7 @@ export function links() {
 }
 
 export default function App() {
-  const { userRole, ENV, frontendJWT } = useLoaderData<typeof loader>();
+  const { userRole, ENV, frontendJWT, isPublicPath } = useLoaderData<typeof loader>();
 
 
   return (
@@ -198,7 +250,7 @@ export default function App() {
             --color-primary-hover: #005a3f;
             --color-primary-light: rgba(0, 104, 74, 0.1);
             --primary-color: #00684a;
-            
+
             /* 成功、警告、错误颜色 */
             --color-success: #52c41a;
             --color-warning: #faad14;
@@ -216,9 +268,17 @@ export default function App() {
       <body className="font-sans">
         <MessageModalProvider>
           <ToastProvider>
-            <Layout userRole={userRole} frontendJWT={frontendJWT}>
+            {/* 客户端认证守卫 - 在客户端检查 localStorage 中的 token */}
+            <ClientAuthGuard isPublicPath={isPublicPath} />
+
+            {/* 🔑 公共路径（登录页、回调页）不显示 Layout，直接渲染内容 */}
+            {isPublicPath ? (
               <Outlet />
-            </Layout>
+            ) : (
+              <Layout userRole={userRole} frontendJWT={frontendJWT}>
+                <Outlet />
+              </Layout>
+            )}
             <RouteChangeLoader />
           </ToastProvider>
         </MessageModalProvider>
@@ -236,10 +296,20 @@ export function ErrorBoundary() {
   // 为错误页面设置标题和描述
   let title = "发生错误";
   let message = "发生了一个未知错误，请稍后重试";
+  let statusText = "服务器错误";
 
   if (isRouteErrorResponse(error)) {
     title = `错误 ${error.status}`;
-    message = error.data?.message || "发生了一个错误，请稍后重试";
+
+    // 特殊处理 403 错误
+    if (error.status === 403) {
+      title = "访问被拒绝";
+      message = typeof error.data === 'string' ? error.data : "您没有权限访问此页面，请联系管理员获取相应权限";
+      statusText = "无权访问";
+    } else {
+      message = error.data?.message || error.data || "发生了一个错误，请稍后重试";
+      statusText = error.statusText || "错误";
+    }
   } else {
     title = "意外错误";
     message = "服务器发生了意外错误，请稍后重试";
@@ -257,7 +327,7 @@ export function ErrorBoundary() {
       <body>
         <AppErrorBoundary
           status={isRouteErrorResponse(error) ? error.status : 500}
-          statusText={isRouteErrorResponse(error) ? error.statusText : "服务器错误"}
+          statusText={statusText}
           message={message}
         />
         <Scripts />
diff --git a/app/routes/_index.tsx b/app/routes/_index.tsx
index 7b77c96..af0c85a 100644
--- a/app/routes/_index.tsx
+++ b/app/routes/_index.tsx
@@ -28,38 +28,58 @@ export async function action({ request }: ActionFunctionArgs) {
   return null;
 }
 
-// 验证用户登录状态
+// 获取用户信息（不再检查服务端认证）
 export async function loader({ request }: LoaderFunctionArgs) {
-  const { isAuthenticated, userRole, userInfo } = await getUserSession(request);
+  // ⚠️ 不再检查服务端 session 认证
+  // 认证检查由 ClientAuthGuard 在客户端进行
 
-  if (!isAuthenticated) {
-    return redirect("/login");
-  }
+  const { userRole, userInfo } = await getUserSession(request);
+
+  // 返回用户信息给客户端（可能为空）
   return Response.json({ userRole, userInfo });
 }
 
 export default function Index() {
   const navigate = useNavigate();
-  const { userRole, userInfo } = useLoaderData<typeof loader>();
+  const loaderData = useLoaderData<typeof loader>();
   const [currentDateTime, setCurrentDateTime] = useState({
     date: '',
     time: ''
   });
-  
+
   // 检查是否通过51707端口访问
   const [isPort51707, setIsPort51707] = useState(false);
-  
+
+  // 用户信息：优先使用服务端返回的，否则从 localStorage 读取
+  const [userInfo, setUserInfo] = useState(loaderData.userInfo);
+  const [userRole, setUserRole] = useState(loaderData.userRole);
+
   useEffect(() => {
     if (typeof window !== 'undefined') {
       setIsPort51707(window.location.port === '51707');
-      // setIsPort51707(window.location.port === '5178');
-    }
-  }, []);
 
-  // 打印服务器端传递的用户角色
+      // 如果服务端没有返回用户信息，从 localStorage 读取
+      if (!loaderData.userInfo || !loaderData.userRole) {
+        const storedUserInfoStr = localStorage.getItem('user_info');
+        if (storedUserInfoStr) {
+          try {
+            const storedUserInfo = JSON.parse(storedUserInfoStr);
+            console.log('📖 [Index] 从 localStorage 读取用户信息:', storedUserInfo);
+            setUserInfo(storedUserInfo);
+            setUserRole(storedUserInfo.user_role || '');
+          } catch (error) {
+            console.error('❌ [Index] 解析 localStorage 用户信息失败:', error);
+          }
+        }
+      }
+    }
+  }, [loaderData.userInfo, loaderData.userRole]);
+
+  // 打印用户角色
   useEffect(() => {
-    console.log('_index 服务器返回的用户角色:', userRole);
-  }, [userRole]);
+    console.log('📋 [Index] 当前用户角色:', userRole);
+    console.log('👤 [Index] 当前用户信息:', userInfo);
+  }, [userRole, userInfo]);
 
   // 更新日期时间
   useEffect(() => {
diff --git a/app/routes/callback.tsx b/app/routes/callback.tsx
index 3c4b513..0ecb28c 100644
--- a/app/routes/callback.tsx
+++ b/app/routes/callback.tsx
@@ -1,8 +1,10 @@
 import { type LoaderFunctionArgs, redirect } from "@remix-run/node";
-import { createUserSession, saveUserInfo, sessionStorage } from "~/api/login/auth.server";
+import { useEffect } from "react";
+import { useSearchParams } from "@remix-run/react";
+import { createUserSession, sessionStorage } from "~/api/login/auth.server";
 import { OAuthClient } from "~/api/login/oauth-client";
 import { getServerOAuthConfigRuntime } from "~/config/oauth-secret.server";
-import { JWTUtils, type UserInfoForJWT } from "~/utils/jwt";
+import { loginWithOAuth, type LoginRequest } from "~/api/login/login-client";
 
 /**
  * 端口号到地区的映射关系
@@ -49,6 +51,30 @@ export async function loader({ request }: LoaderFunctionArgs) {
   const error = url.searchParams.get("error");
   const error_description = url.searchParams.get("error_description");
 
+  // 🔑 检查是否是管理员账密登录（直接传递 token 和 userInfo）
+  const token = url.searchParams.get("token");
+  const userInfo = url.searchParams.get("userInfo");
+  const redirectTo = url.searchParams.get("redirectTo") || "/";
+
+  // 🔑 如果有 token 和 userInfo，说明是管理员账密登录
+  // login.tsx action 已经创建了 Cookie Session，这里只需要返回 null
+  // 让客户端组件从 URL 读取 token 并保存到 localStorage
+  if (token && userInfo) {
+    console.log("✅ [Callback] 检测到管理员账密登录，交给客户端处理");
+
+    // 验证 userInfo 格式（防止解析错误）
+    try {
+      JSON.parse(decodeURIComponent(userInfo));
+    } catch (error) {
+      console.error("❌ [Callback] 解析管理员登录用户信息失败:", error);
+      return redirectToLoginWithError(request, "登录失败：用户信息格式错误");
+    }
+
+    // ✅ 直接返回 null，让客户端 useEffect 处理
+    // 注意：Cookie Session 已经在 login.tsx action 中通过 createUserSession 创建
+    return null;
+  }
+
   // console.log("🔧 OAuth2.0回调参数:", {
   //   code: code ? `${code.substring(0, 10)}...` : null,
   //   state: state,
@@ -119,81 +145,79 @@ export async function loader({ request }: LoaderFunctionArgs) {
     }
     console.log("✅ [Callback] 用户信息获取成功");
 
-
-    // TODO 根据用户信息判断用户角色，这里可以根据实际业务逻辑调整 暂定都是common
-    const userRole = "common";
-
     // 获取重定向URL
     const redirectTo = url.searchParams.get("redirect") || "/";
 
-    // 🔒 安全：临时 JWT 现在在 saveUserInfo() 内部生成，避免在客户端代码中暴露 user_id 逻辑
-    // 成功获取用户信息之后通过auth.server.ts中的saveUserInfo方法去写入自己的数据库中，通过sub作为唯一值去添加数据
-    const saveResult = await saveUserInfo(
-      userInfo.data,
-      userRole,
-      tokenResponse.expires_in,
-      area
-    );
-    if (!saveResult.success) {
-      console.error("保存用户信息到数据库失败:", saveResult.error);
+    // 调用后端登录接口,传递 OAuth 用户信息,获取 JWT token
+    const loginRequest: LoginRequest = {
+      userInfo: userInfo.data,
+      expiresIn: tokenResponse.expires_in,
+      area: area
+    };
 
-      // 🔑 保存用户信息失败，需要清除 IDaaS 登录状态
+    const loginResponse = await loginWithOAuth(loginRequest);
+
+    if (!loginResponse.success || !loginResponse.data) {
+      console.error("❌ [Callback] 后端登录失败:", loginResponse.error);
+
+      // 🔑 登录失败，需要清除 IDaaS 登录状态
       try {
         const logoutUrl = `${url.protocol}//${url.host}/login`;
         const logoutSuccess = await oauthClient.logout(tokenResponse.access_token, logoutUrl);
         if (logoutSuccess) {
-          console.log("✅ [Callback] 已清除 IDaaS 登录状态（数据库保存失败）");
+          console.log("✅ [Callback] 已清除 IDaaS 登录状态（后端登录失败）");
         } else {
-          console.warn("⚠️ [Callback] 清除 IDaaS 登录状态失败（数据库保存失败）");
+          console.warn("⚠️ [Callback] 清除 IDaaS 登录状态失败（后端登录失败）");
         }
       } catch (logoutError) {
-        console.error("❌ [Callback] 调用 IDaaS 登出时出错（数据库保存失败）:", logoutError);
+        console.error("❌ [Callback] 调用 IDaaS 登出时出错（后端登录失败）:", logoutError);
       }
 
-      return redirectToLoginWithError(request, "保存用户信息失败，请重新登录");
+      return redirectToLoginWithError(request, loginResponse.error || "登录失败，请重新登录");
     }
 
-    console.log("用户信息已成功保存到数据库，地区:", area || "未设置");
-    const savedUserData = saveResult.data!;
+    console.log("✅ [Callback] 后端登录成功，JWT token 已获取");
+    const frontendJWT = loginResponse.data.access_token;
+    const savedUserInfo = loginResponse.data.user_info;
 
-    // 生成前端专用JWT（使用完整的用户信息，包括数据库 ID）
-    const jwtUserInfo: UserInfoForJWT = {
-      sub: userInfo.data.sub,
-      user_id: savedUserData.id!,
-      username: savedUserData.username,
-      nick_name: savedUserData.nick_name,
-      email: savedUserData.email,
-      phone_number: savedUserData.phone_number,
-      ou_id: savedUserData.ou_id,
-      ou_name: savedUserData.ou_name,
-      is_leader: savedUserData.is_leader,
-      user_role: userRole as 'common' | 'developer'
-    };
-
-    const frontendJWT = JWTUtils.generateJWT(jwtUserInfo, tokenResponse.expires_in);
-    // console.log("前端JWT已生成");
-    
-    // 更新userInfo以包含数据库ID、JWT，并用数据库标准字段覆盖关键属性，确保 nick_name 等存在
+    // 更新userInfo以包含数据库ID、JWT（user_role 从后端返回）
     const enhancedUserInfo = {
       ...userInfo.data, // 保留OAuth返回的原字段（包含 nickname 等）
-      username: savedUserData.username,
-      nick_name: savedUserData.nick_name,
-      phone_number: savedUserData.phone_number,
-      email: savedUserData.email,
-      ou_id: savedUserData.ou_id,
-      ou_name: savedUserData.ou_name,
-      status: savedUserData.status,
-      is_leader: savedUserData.is_leader,
-      user_id: savedUserData.id,
-      user_role: userRole,
+      username: savedUserInfo.username,
+      nick_name: savedUserInfo.nick_name,
+      phone_number: savedUserInfo.phone_number,
+      email: savedUserInfo.email,
+      ou_id: savedUserInfo.ou_id,
+      ou_name: savedUserInfo.ou_name,
+      is_leader: savedUserInfo.is_leader,
+      user_id: savedUserInfo.user_id,
+      user_role: savedUserInfo.user_role, // 使用后端返回的角色
       frontend_jwt: frontendJWT
     };
 
+    // 🔑 重要：将 token 和用户信息作为 URL 参数传递给客户端
+    // 客户端 useEffect 会将其保存到 localStorage
+    const callbackUrl = new URL('/callback', url.origin);
+    callbackUrl.searchParams.set('token', frontendJWT);
+    callbackUrl.searchParams.set('userInfo', encodeURIComponent(JSON.stringify({
+      user_id: savedUserInfo.user_id,
+      username: savedUserInfo.username,
+      nick_name: savedUserInfo.nick_name,
+      email: savedUserInfo.email,
+      phone_number: savedUserInfo.phone_number,
+      ou_id: savedUserInfo.ou_id,
+      ou_name: savedUserInfo.ou_name,
+      is_leader: savedUserInfo.is_leader,
+      user_role: savedUserInfo.user_role,
+      sub: userInfo.data.sub
+    })));
+    callbackUrl.searchParams.set('redirectTo', redirectTo);
+
     // 使用统一的session创建函数
     return createUserSession({
       isAuthenticated: true,
-      userRole: userRole,
-      redirectTo,
+      userRole: savedUserInfo.user_role, // 使用后端返回的角色
+      redirectTo: callbackUrl.toString(), // 先跳转到 callback 页面保存 token
       accessToken: tokenResponse.access_token,
       refreshToken: tokenResponse.refresh_token,
       tokenExpiresIn: tokenResponse.expires_in,
@@ -224,11 +248,49 @@ export async function loader({ request }: LoaderFunctionArgs) {
 }
 
 export default function Callback() {
+  const [searchParams] = useSearchParams();
+
+  useEffect(() => {
+    // 从 URL 参数中获取 token（如果有）
+    const token = searchParams.get("token");
+    const userInfo = searchParams.get("userInfo");
+    const redirectTo = searchParams.get("redirectTo") || "/";
+
+    if (token && typeof window !== 'undefined') {
+      console.log('🔑 [Callback] 开始保存 token 到 localStorage');
+
+      // 存储 token 到 localStorage
+      localStorage.setItem('access_token', token);
+      console.log('✅ [Callback] Token 已存储到 localStorage');
+
+      // 存储用户信息
+      if (userInfo) {
+        try {
+          const parsedUserInfo = JSON.parse(decodeURIComponent(userInfo));
+          localStorage.setItem('user_info', JSON.stringify(parsedUserInfo));
+          console.log('✅ [Callback] 用户信息已存储到 localStorage:', parsedUserInfo);
+        } catch (error) {
+          console.error('❌ [Callback] 解析用户信息失败:', error);
+        }
+      }
+
+      // ⏱️ 短暂延迟后跳转，确保 localStorage 写入完成
+      // 使用 requestAnimationFrame 确保 DOM 更新后立即跳转
+      requestAnimationFrame(() => {
+        setTimeout(() => {
+          console.log(`🚀 [Callback] 跳转到目标页面: ${redirectTo}`);
+          window.location.href = redirectTo;
+        }, 100); // 减少延迟从 500ms 到 100ms
+      });
+    }
+  }, [searchParams]);
+
   return (
     <div className="flex items-center justify-center min-h-screen">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500 mx-auto"></div>
         <p className="mt-4 text-gray-600">正在处理登录...</p>
+        <p className="mt-2 text-sm text-gray-500">即将跳转...</p>
       </div>
     </div>
   );
diff --git a/app/routes/contract-search._index.tsx b/app/routes/contract-search._index.tsx
deleted file mode 100644
index 28f0b85..0000000
--- a/app/routes/contract-search._index.tsx
+++ /dev/null
@@ -1,152 +0,0 @@
-// import { useState } from 'react';
-// import styles from '~/styles/pages/contract-search.css?url';
-
-// export const links = () => [
-//   { rel: 'stylesheet', href: styles }
-// ];
-
-// export default function ContractSearchIndex() {
-//   const [searchQuery, setSearchQuery] = useState('');
-  
-//   const handleSearchInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-//     setSearchQuery(e.target.value);
-//     // 自动调整高度
-//     e.target.style.height = 'auto';
-//     e.target.style.height = Math.max(80, e.target.scrollHeight) + 'px';
-//   };
-
-//   const handleSearch = () => {
-//     if (searchQuery.trim()) {
-//       console.log('搜索查询:', searchQuery);
-//       // 这里可以添加实际的搜索逻辑
-//     }
-//   };
-
-//   const handleCategoryClick = (categoryName: string) => {
-//     console.log('选择分类:', categoryName);
-//     // 这里可以添加跳转到相应分类的逻辑
-//   };
-
-//   const handleKeyDown = (e: React.KeyboardEvent, categoryName: string) => {
-//     if (e.key === 'Enter' || e.key === ' ') {
-//       e.preventDefault();
-//       handleCategoryClick(categoryName);
-//     }
-//   };
-
-//   return (
-//     <div className="content-area">
-//       <div className="search-hero">
-//         <h1 className="search-title">AI智能合同模板搜索</h1>
-//         <p className="search-subtitle">输入合同名称、用途或关键内容，快速找到最适合的模板</p>
-        
-//         <div className="search-container">
-//           <div className="search-box">
-//             <textarea 
-//               className="search-textarea" 
-//               placeholder="例如：销售合同、设备采购协议、包含违约责任条款的合同..."
-//               value={searchQuery}
-//               onChange={handleSearchInputChange}
-//               aria-label="搜索输入框"
-//             ></textarea>
-//             <div className="search-actions">
-//               <div className="search-tips">
-//                 <i className="ri-lightbulb-line mr-1"></i>
-//                 支持自然语言描述，AI将为您匹配最相关的模板
-//               </div>
-//               <button 
-//                 className="search-btn" 
-//                 onClick={handleSearch}
-//                 aria-label="开始搜索"
-//               >
-//                 <i className="ri-search-line"></i>
-//                 智能搜索
-//               </button>
-//             </div>
-//           </div>
-//         </div>
-//       </div>
-      
-//       <div className="quick-categories">
-//         <button 
-//           className="category-card" 
-//           onClick={() => handleCategoryClick('销售合同')}
-//           onKeyDown={(e) => handleKeyDown(e, '销售合同')}
-//           tabIndex={0}
-//           aria-label="销售合同分类"
-//         >
-//           <div className="category-icon">
-//             <i className="ri-handshake-line"></i>
-//           </div>
-//           <div className="category-title">销售合同</div>
-//           <div className="category-count">128个模板</div>
-//         </button>
-//         <button 
-//           className="category-card" 
-//           onClick={() => handleCategoryClick('采购合同')}
-//           onKeyDown={(e) => handleKeyDown(e, '采购合同')}
-//           tabIndex={0}
-//           aria-label="采购合同分类"
-//         >
-//           <div className="category-icon">
-//             <i className="ri-shopping-cart-line"></i>
-//           </div>
-//           <div className="category-title">采购合同</div>
-//           <div className="category-count">96个模板</div>
-//         </button>
-//         <button 
-//           className="category-card" 
-//           onClick={() => handleCategoryClick('物流运输')}
-//           onKeyDown={(e) => handleKeyDown(e, '物流运输')}
-//           tabIndex={0}
-//           aria-label="物流运输分类"
-//         >
-//           <div className="category-icon">
-//             <i className="ri-truck-line"></i>
-//           </div>
-//           <div className="category-title">物流运输</div>
-//           <div className="category-count">64个模板</div>
-//         </button>
-//         <button 
-//           className="category-card" 
-//           onClick={() => handleCategoryClick('人事劳务')}
-//           onKeyDown={(e) => handleKeyDown(e, '人事劳务')}
-//           tabIndex={0}
-//           aria-label="人事劳务分类"
-//         >
-//           <div className="category-icon">
-//             <i className="ri-user-settings-line"></i>
-//           </div>
-//           <div className="category-title">人事劳务</div>
-//           <div className="category-count">52个模板</div>
-//         </button>
-//         <button 
-//           className="category-card" 
-//           onClick={() => handleCategoryClick('租赁合同')}
-//           onKeyDown={(e) => handleKeyDown(e, '租赁合同')}
-//           tabIndex={0}
-//           aria-label="租赁合同分类"
-//         >
-//           <div className="category-icon">
-//             <i className="ri-building-line"></i>
-//           </div>
-//           <div className="category-title">租赁合同</div>
-//           <div className="category-count">38个模板</div>
-//         </button>
-//         <button 
-//           className="category-card" 
-//           onClick={() => handleCategoryClick('保密协议')}
-//           onKeyDown={(e) => handleKeyDown(e, '保密协议')}
-//           tabIndex={0}
-//           aria-label="保密协议分类"
-//         >
-//           <div className="category-icon">
-//             <i className="ri-shield-check-line"></i>
-//           </div>
-//           <div className="category-title">保密协议</div>
-//           <div className="category-count">24个模板</div>
-//         </button>
-//       </div>
-//     </div>
-//   );
-// }
diff --git a/app/routes/contract-search.tsx b/app/routes/contract-search.tsx
deleted file mode 100644
index 5f6ec27..0000000
--- a/app/routes/contract-search.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-import { Outlet } from "@remix-run/react";
-import { type MetaFunction } from "@remix-run/node";
-
-export const meta: MetaFunction = () => {
-  return [
-    { title: "智能搜索 - 中国烟草AI合同及卷宗审核系统" },
-    { 
-      name: "contract-search", 
-      content: "智能搜索模块，包括智能搜索功能" 
-    }
-  ];
-};
-
-export const handle = {
-  breadcrumb: "智能搜索"
-};
-
-/**
- * 配置列表路由布局
- */
-export default function ContractSearchLayout() {
-  return <Outlet />;
-}
\ No newline at end of file
diff --git a/app/routes/debug.tsx b/app/routes/debug.tsx
deleted file mode 100644
index 882ee26..0000000
--- a/app/routes/debug.tsx
+++ /dev/null
@@ -1,56 +0,0 @@
-import { useLocation, Link } from "@remix-run/react";
-
-export default function DebugPage() {
-  const location = useLocation();
-
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold mb-4">路由诊断页面</h1>
-      
-      <div className="bg-gray-100 p-4 rounded mb-6">
-        <h2 className="text-xl font-semibold mb-2">当前路径信息</h2>
-        <pre className="bg-white p-3 rounded border">
-          {JSON.stringify({
-            pathname: location.pathname,
-            search: location.search,
-            hash: location.hash,
-            key: location.key,
-            state: location.state
-          }, null, 2)}
-        </pre>
-      </div>
-      
-      <div className="mb-6">
-        <h2 className="text-xl font-semibold mb-2">测试链接</h2>
-        <div className="flex flex-col space-y-2">
-          <Link to="/" className="text-blue-500 hover:underline">首页 - /</Link>
-          <Link to="/rules" className="text-blue-500 hover:underline">评查点列表 - /rules</Link>
-          <Link to="/rules/1" className="text-blue-500 hover:underline">评查点详情 - /rules/1</Link>
-          <a href="/rules" className="text-green-500 hover:underline">原生链接 - /rules</a>
-        </div>
-      </div>
-      
-      <div>
-        <h2 className="text-xl font-semibold mb-2">跳转测试</h2>
-        <button 
-          onClick={() => {
-            window.location.href = '/rules';
-          }}
-          className="bg-blue-500 text-white px-4 py-2 rounded mr-2 hover:bg-blue-600"
-        >
-          直接跳转到 /rules
-        </button>
-        
-        <button 
-          onClick={() => {
-            window.history.pushState({}, '', '/rules');
-            window.dispatchEvent(new PopStateEvent('popstate'));
-          }}
-          className="bg-green-500 text-white px-4 py-2 rounded hover:bg-green-600"
-        >
-          使用History API跳转到 /rules
-        </button>
-      </div>
-    </div>
-  );
-} 
\ No newline at end of file
diff --git a/app/routes/documents.edit.tsx b/app/routes/documents.edit.tsx
index e3a286b..4b9f62e 100644
--- a/app/routes/documents.edit.tsx
+++ b/app/routes/documents.edit.tsx
@@ -468,10 +468,10 @@ export default function DocumentEdit() {
       <div className="page-header">
         <h2 className="page-title">修改文档信息</h2>
         <div>
-          <Button 
-            type="default" 
+          <Button
+            type="default"
             icon="ri-arrow-left-line"
-            onClick={() => navigate("/documents")}
+            onClick={() => navigate("/documents/list")}
             className="mr-2"
           >
             返回列表
@@ -712,9 +712,9 @@ export function ErrorBoundary() {
     <div className="error-container">
       <h1 className="text-xl font-bold text-red-500 mb-4">出错了</h1>
       <p className="mb-4">文档编辑页面加载失败。请检查文档ID是否正确，或稍后重试。</p>
-      <Button 
-        type="primary" 
-        to="/documents"
+      <Button
+        type="primary"
+        to="/documents/list"
       >
         返回文档列表
       </Button>
diff --git a/app/routes/documents._index.tsx b/app/routes/documents.list.tsx
similarity index 79%
rename from app/routes/documents._index.tsx
rename to app/routes/documents.list.tsx
index 9bbf5b5..ef562b7 100644
--- a/app/routes/documents._index.tsx
+++ b/app/routes/documents.list.tsx
@@ -10,7 +10,9 @@ import { FileTag } from "~/components/ui/FileTag";
 import { FilterPanel, FilterSelect, SearchFilter, DateRangeFilter } from "~/components/ui/FilterPanel";
 import { TableRowSkeleton, LoadingIndicator, NumberSkeleton } from '~/components/ui/SkeletonScreen';
 import documentsIndexStyles from "~/styles/pages/documents_index.css?url";
-import { getDocuments, deleteDocument, type DocumentUI } from "~/api/files/documents";
+import documentVersionStyles from "~/styles/components/document-version.css?url";
+import { getDocuments, getDocumentsWithVersionInfo, getDocumentHistory, deleteDocument, type DocumentUI, type DocumentVersionUI } from "~/api/files/documents";
+import { IssuesDiff } from "~/components/ui/IssuesDiff";
 import { getDocumentTypes } from "~/api/document-types/document-types";
 import { updateDocumentAuditStatus } from "~/api/evaluation_points/rules-files";
 import { appendContractAttachments, uploadContractTemplate } from "~/api/files/files-upload";
@@ -22,7 +24,8 @@ import { DOCUMENT_URL } from "~/api/axios-client";
 // 导入样式
 export function links() {
   return [
-    { rel: "stylesheet", href: documentsIndexStyles }
+    { rel: "stylesheet", href: documentsIndexStyles },
+    { rel: "stylesheet", href: documentVersionStyles }
   ];
 }
 
@@ -34,7 +37,7 @@ export const meta: MetaFunction = () => {
   ];
 };
 
-// 数据加载器 
+// 数据加载器
 export const loader = async ({ request }: LoaderFunctionArgs) => {
   // 获取用户会话信息
   const { getUserSession } = await import("~/api/login/auth.server");
@@ -45,7 +48,7 @@ export const loader = async ({ request }: LoaderFunctionArgs) => {
   const page = parseInt(url.searchParams.get("page") || "1", 10);
   const pageSize = parseInt(url.searchParams.get("pageSize") || "10", 10);
 
-  // 获取文档类型列表，用于筛选条件
+  // 获取文档类型列表（服务端需要显式传递 token，客户端依赖 axios 拦截器）
   const typesResponse = await getDocumentTypes({ pageSize: 500 }, frontendJWT);
   const documentTypes = typesResponse.data?.types || [];
   const documentTypeOptions = documentTypes.map(type => ({
@@ -61,7 +64,6 @@ export const loader = async ({ request }: LoaderFunctionArgs) => {
     pageSize,
     documentTypeOptions,
     userInfo, // 传递用户信息到客户端
-    frontendJWT, // 传递前端JWT到客户端
     initialLoad: true // 标记这是初始加载
   });
 };
@@ -180,19 +182,40 @@ export default function DocumentsIndex() {
   const loaderData = useLoaderData<typeof loader>();
   const fetcher = useFetcher<ActionResponse>();
   const navigate = useNavigate();
-  
+
   // 存储从 sessionStorage 获取的 reviewType
   const [reviewType, setReviewType] = useState<string | null>(null);
-  
+
   // 添加页面加载状态管理
   const [isLoadingData, setIsLoadingData] = useState(true);
   const [documents, setDocuments] = useState<DocumentUI[]>([]);
   const [total, setTotal] = useState(0);
   const [filteredDocumentTypeOptions, setFilteredDocumentTypeOptions] = useState(loaderData.documentTypeOptions);
   const dataCache = useRef<typeof loaderData | null>(null);
-  
+
   // 添加一个状态来跟踪是否执行了删除操作
   const [isDeleting, setIsDeleting] = useState(false);
+
+  // 辅助函数：从 localStorage 获取用户ID（与 token 管理保持一致）
+  const getUserId = useCallback((): string | undefined => {
+    if (typeof window === 'undefined') return undefined;
+
+    const userInfoStr = localStorage.getItem('user_info');
+    if (!userInfoStr) return undefined;
+
+    try {
+      const userInfoData = JSON.parse(userInfoStr);
+      return userInfoData.user_id?.toString();
+    } catch (error) {
+      console.error('解析 localStorage 用户信息失败:', error);
+      return undefined;
+    }
+  }, []);
+
+  // 版本管理：展开的文档行
+  const [expandedRows, setExpandedRows] = useState<Set<number>>(new Set());
+  // 版本管理：正在加载历史版本的文档
+  const [loadingHistory, setLoadingHistory] = useState<Set<number>>(new Set());
   
   // 附件追加和模板上传状态
   const [showAttachmentUpload, setShowAttachmentUpload] = useState<boolean>(false);
@@ -240,12 +263,18 @@ export default function DocumentsIndex() {
   const fetchData = useCallback(async (storedReviewType: string) => {
     setIsLoadingData(true);
     loadingBarService.show();
-    
+
     try {
-      // 从loader data中获取用户ID
-      const userId = loaderData.userInfo?.user_id?.toString();
-      
-      // 构建搜索参数
+      // 从 localStorage 获取用户ID（与 token 管理保持一致）
+      const userId = getUserId();
+      if (!userId) {
+        toastService.error('用户身份验证失败，无法获取文档列表');
+        setIsLoadingData(false);
+        loadingBarService.hide();
+        return;
+      }
+
+      // 构建搜索参数（token 由 axios 拦截器自动从 localStorage 获取）
       const searchParams = {
         name: search || undefined,
         documentNumber: documentNumber || undefined,
@@ -257,21 +286,20 @@ export default function DocumentsIndex() {
         reviewType: storedReviewType || undefined,
         userId: userId, // 添加用户ID筛选
         page: currentPage,
-        pageSize,
-        token: loaderData.frontendJWT || undefined // 传递 JWT token
+        pageSize
       };
 
-      // 获取文档列表
-      const documentsResponse = await getDocuments(searchParams);
+      // 获取文档列表（带版本信息）
+      const documentsResponse = await getDocumentsWithVersionInfo(searchParams);
       if (documentsResponse.error) {
         throw new Error(documentsResponse.error);
       }
 
-      // 获取经过过滤的文档类型列表
-      const filteredTypesResponse = await getDocumentTypes({ 
-        pageSize: 500, 
-        reviewType: storedReviewType || undefined 
-      }, loaderData.frontendJWT || undefined);
+      // 获取经过过滤的文档类型列表（token 由 axios 拦截器自动获取）
+      const filteredTypesResponse = await getDocumentTypes({
+        pageSize: 500,
+        reviewType: storedReviewType || undefined
+      });
       const filteredDocumentTypes = filteredTypesResponse.data?.types || [];
       const filteredOptions = filteredDocumentTypes.map(type => ({
         value: type.id,
@@ -290,7 +318,7 @@ export default function DocumentsIndex() {
       setIsLoadingData(false);
       loadingBarService.hide();
     }
-  }, [search, documentNumber, documentType, auditStatus, fileStatus, dateFrom, dateTo, currentPage, pageSize, loaderData.userInfo]);
+  }, [search, documentNumber, documentType, auditStatus, fileStatus, dateFrom, dateTo, currentPage, pageSize, getUserId]);
 
   // 在组件挂载时从 sessionStorage 获取 reviewType 并加载数据
   useEffect(() => {
@@ -707,17 +735,17 @@ export default function DocumentsIndex() {
   // 开始审核
   const handleReviewFileClick = async (fileId: number, auditStatus: number | null) => {
     // 检查audit_status是否为0，如果是则更新为2
-    if (auditStatus === 0 || auditStatus === null) {  
+    if (auditStatus === 0 || auditStatus === null) {
       try {
-        // 从loader data中获取用户ID
-        const userId = loaderData.userInfo?.user_id?.toString();
+        // 从 localStorage 获取用户ID（与 token 管理保持一致）
+        const userId = getUserId();
         if (!userId) {
           toastService.error('用户身份验证失败');
           return;
         }
-        
+
         // console.log('开始审核',fileId,auditStatus)
-        const response = await updateDocumentAuditStatus(fileId.toString(), 2, userId, loaderData.frontendJWT as string | undefined);
+        const response = await updateDocumentAuditStatus(fileId.toString(), 2, userId);
         if (response.error) {
           console.error('更新文件审核状态失败:', response.error);
           toastService.error('更新文件审核状态失败:' + (response.error || '未知错误'));
@@ -796,8 +824,7 @@ export default function DocumentsIndex() {
         attachmentFiles,
         attachmentMergeMode,
         true, // isReprocess
-        attachmentRemark || undefined,
-        loaderData.frontendJWT as string | undefined
+        attachmentRemark || undefined
       );
 
       if (result.error) {
@@ -868,8 +895,7 @@ export default function DocumentsIndex() {
       const result = await uploadContractTemplate(
         templateFile,
         selectedDocumentId,
-        undefined, // comparisonId
-        loaderData.frontendJWT as string | undefined
+        undefined // comparisonId
       );
 
       if (result.error) {
@@ -896,6 +922,165 @@ export default function DocumentsIndex() {
     }
   };
 
+  // 展开/折叠历史版本
+  const handleToggleExpand = async (doc: DocumentUI) => {
+    const newExpanded = new Set(expandedRows);
+    const newLoading = new Set(loadingHistory);
+
+    if (expandedRows.has(doc.id)) {
+      // 折叠：移除展开状态
+      newExpanded.delete(doc.id);
+      setExpandedRows(newExpanded);
+
+      // 清空历史版本数据
+      setDocuments(prevDocs =>
+        prevDocs.map(d =>
+          d.id === doc.id ? { ...d, historyVersions: undefined, isExpanded: false } : d
+        )
+      );
+    } else {
+      // 展开：加载历史版本
+      newExpanded.add(doc.id);
+      setExpandedRows(newExpanded);
+
+      // 如果还没有加载历史版本，则加载
+      if (!doc.historyVersions && doc.historyCount && doc.historyCount > 0) {
+        newLoading.add(doc.id);
+        setLoadingHistory(newLoading);
+
+        try {
+          // 从 localStorage 获取用户ID（与 token 管理保持一致）
+          const userId = getUserId();
+          if (!userId) {
+            toastService.error('用户身份验证失败');
+            newExpanded.delete(doc.id);
+            setExpandedRows(newExpanded);
+            newLoading.delete(doc.id);
+            setLoadingHistory(newLoading);
+            return;
+          }
+
+          const result = await getDocumentHistory(
+            doc.name,
+            userId,
+            doc.id
+          );
+
+          if (result.data) {
+            // 更新文档的历史版本数据
+            setDocuments(prevDocs =>
+              prevDocs.map(d =>
+                d.id === doc.id
+                  ? { ...d, historyVersions: result.data, isExpanded: true }
+                  : d
+              )
+            );
+          } else if (result.error) {
+            toastService.error(`加载历史版本失败: ${result.error}`);
+            // 加载失败时取消展开
+            newExpanded.delete(doc.id);
+            setExpandedRows(newExpanded);
+          }
+        } catch (error) {
+          console.error('加载历史版本失败:', error);
+          toastService.error('加载历史版本失败');
+          newExpanded.delete(doc.id);
+          setExpandedRows(newExpanded);
+        } finally {
+          newLoading.delete(doc.id);
+          setLoadingHistory(newLoading);
+        }
+      } else {
+        // 已经加载过，只更新展开状态
+        setDocuments(prevDocs =>
+          prevDocs.map(d =>
+            d.id === doc.id ? { ...d, isExpanded: true } : d
+          )
+        );
+      }
+    }
+  };
+
+  // 渲染历史版本行的辅助函数
+  const renderHistoryRow = (historyDoc: DocumentVersionUI, parentDoc: DocumentUI) => {
+    return (
+      <tr key={`history-${historyDoc.id}`} className="history-row">
+        <td className="align-middle">
+          <input type="checkbox" disabled style={{ visibility: 'hidden' }} />
+        </td>
+        <td className="align-middle">
+          <div className="flex items-center justify-center gap-3">
+            <i className="ri-history-line text-gray-400 text-lg"></i>
+            <span className="history-version-label">
+              v{historyDoc.versionNumber} 版本
+            </span>
+          </div>
+        </td>
+        <td className="text-xs text-gray-600 px-4">{historyDoc.documentNumber}</td>
+        <td className="text-xs text-gray-600 px-4">{formatFileSize(historyDoc.size)}</td>
+        <td className="px-4">
+          <div className={`inline-flex items-center px-2 py-1 rounded-full text-xs bg-green-100 text-green-800`}>
+            <i className="ri-check-line mr-1"></i>
+            <span>{fileProcessingStatusOptions.find(s => s.value === historyDoc.fileStatus)?.label || '已完成'}</span>
+          </div>
+        </td>
+        <td className="px-4">
+          <div className={`inline-flex items-center px-2 py-1 rounded-full text-xs ${
+            historyDoc.auditStatus === 1 ? 'bg-green-100 text-green-800' :
+            historyDoc.auditStatus === -1 ? 'bg-red-100 text-red-800' :
+            'bg-blue-100 text-blue-800'
+          }`}>
+            <i className={`${auditStatusMapping[historyDoc.auditStatus]?.icon || 'ri-time-line'} mr-1`}></i>
+            <span>{auditStatusMapping[historyDoc.auditStatus]?.label || '待审核'}</span>
+          </div>
+        </td>
+        <td className="px-4">
+          <IssuesDiff
+            currentIssues={historyDoc.issues}
+            previousIssues={undefined}
+            issuesDiff={historyDoc.issuesDiff}
+            issuesDiffType={historyDoc.issuesDiffType}
+          />
+        </td>
+        <td className="text-xs text-gray-600 px-4">{historyDoc.uploadTime}</td>
+        <td className="">
+          <div className="operations-cell flex flex-wrap gap-1 px-4">
+            <Link
+              to={`/reviews?id=${historyDoc.id}&previousRoute=documents`}
+              className="text-xs px-2 py-1 h-7 mr-1 hover:underline"
+            >
+              <i className="ri-eye-line"></i>
+              查看
+            </Link>
+            <Link
+              to={`/documents/edit?id=${historyDoc.id}`}
+              className="text-xs px-2 py-1 h-7 mr-1 text-gray-500 hover:underline hover:text-gray-700"
+            >
+              <i className="ri-edit-line"></i>
+              修改
+            </Link>
+            <button
+              type="button"
+              className="text-xs px-2 py-1 h-7 mr-1 text-gray-500 hover:underline hover:text-gray-700"
+              onClick={() => handleDownload(historyDoc.path)}
+            >
+              <i className="ri-download-line"></i>
+              下载
+            </button>
+            <button
+              type="button"
+              className="text-xs px-2 py-1 h-7 text-error hover:underline hover:text-red-700"
+              onClick={() => handleDelete(historyDoc.id.toString(), historyDoc.name, historyDoc.fileStatus)}
+            >
+              <i className="ri-delete-bin-line"></i>
+              删除
+            </button>
+          </div>
+        </td>
+      </tr>
+    );
+  };
+
 
   // 表格列定义
   const columns = [
@@ -922,31 +1107,56 @@ export default function DocumentsIndex() {
       key: "name",
       width:'25%',
       render: (_: unknown, record: DocumentUI) => (
-        <div className="flex m-1">
-          <FileTag 
+        <div className="flex items-center gap-3">
+          {/* 展开/折叠图标（仅在有历史版本时显示） */}
+          {record.historyCount && record.historyCount > 0 ? (
+            loadingHistory.has(record.id) ? (
+              <i className="ri-loader-4-line expand-icon animate-spin" title="加载中..."></i>
+            ) : (
+              <i
+                className={`ri-arrow-right-s-line expand-icon ${expandedRows.has(record.id) ? 'expanded' : ''}`}
+                onClick={() => handleToggleExpand(record)}
+                title={expandedRows.has(record.id) ? '折叠历史版本' : '展开历史版本'}
+              ></i>
+            )
+          ) : (
+            <span style={{ width: '20px', display: 'inline-block' }}></span>
+          )}
+
+          <FileTag
             extension={record.fileType}
-            showIcon={true} 
-            showText={false} 
+            showIcon={true}
+            showText={false}
             showBackground={false}
             size="lg"
-            className="mr-2 flex-shrink-0 self-center"
+            className="flex-shrink-0"
           />
-          <div className="overflow-hidden">
-            <span className="file-name break-words block whitespace-normal leading-normal" title={record.name}>{record.name}</span>
-            <div className="mt-2 flex inline-block">
-              <FileTypeTag 
-                type={record.type} 
+
+          <div className="flex flex-col gap-2 flex-1 min-w-0">
+            <span className="doc-name-text font-medium text-gray-900" title={record.name}>
+              {record.name}
+            </span>
+            <div className="flex items-center gap-2 flex-wrap">
+              <FileTypeTag
+                type={record.type}
                 typeName={record.typeName}
-                text={record.typeName} 
-                size="sm" 
+                text={record.typeName}
+                size="sm"
                 showIcon={false}
                 fileType={record.fileType}
                 colorMode="light"
               />
               {record.isTest && (
-                <span className="ml-2 text-xs bg-gray-100 text-gray-500 px-1 rounded">测试</span>
+                <span className="text-xs bg-gray-100 text-gray-500 px-1 rounded">测试</span>
               )}
-            </div>
+              {/* 版本徽章 - 始终显示 */}
+              {record.historyCount !== undefined && record.historyCount > 0 ? 
+                <span className="version-badge">
+                  <i className="ri-history-line"></i>
+                    v{record.historyCount + 1} {record.historyCount !== undefined && `(共${record.historyCount}个历史版本)`}
+                </span> : ""
+              }         
+              </div> 
           </div>
         </div>
       )
@@ -1004,9 +1214,26 @@ export default function DocumentsIndex() {
     {
       title: "问题数量",
       key: "issues",
-      width:"7%",
+      width:"10%",
       render: (_: unknown, record: DocumentUI) => (
-        record.issues === null ? "-" : record.issues
+        <IssuesDiff
+          currentIssues={record.issues}
+          previousIssues={record.previousIssues}
+          issuesDiff={
+            record.issues != null && record.previousIssues != null
+              ? Math.abs(record.issues - record.previousIssues)
+              : undefined
+          }
+          issuesDiffType={
+            record.issues != null && record.previousIssues != null
+              ? record.issues > record.previousIssues
+                ? 'increase'
+                : record.issues < record.previousIssues
+                ? 'decrease'
+                : 'same'
+              : undefined
+          }
+        />
       )
     },
     {
@@ -1236,13 +1463,57 @@ export default function DocumentsIndex() {
           <div className="overflow-x-auto">
             {isLoadingData && documents.length === 0 ? (
               <TableRowSkeleton count={5} />
+            ) : documents.length === 0 ? (
+              <div className="text-center py-8 text-gray-500">
+                {isLoadingData ? "加载中..." : "暂无数据"}
+              </div>
             ) : (
-              <Table
-                columns={columns}
-                dataSource={documents}
-                rowKey="id"
-                emptyText={isLoadingData ? "加载中..." : "暂无数据"}
-              />
+              <table className="w-full border-collapse">
+                <thead className="bg-gray-50">
+                  <tr>
+                    {columns.map((col, index) => (
+                      <th
+                        key={col.key || index}
+                        style={{ width: col.width }}
+                        className="px-4 py-3 text-left text-sm font-semibold text-gray-700 border-b"
+                      >
+                        {col.title}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {documents.map((doc) => (
+                    <>
+                      {/* 主文档行 */}
+                      <tr key={doc.id} className="border-b hover:bg-gray-50 transition-colors">
+                        {columns.map((col, index) => (
+                          <td key={col.key || index} className="px-4 py-3 text-sm">
+                            {col.render ? col.render(null, doc, index) : (doc as any)[col.key]}
+                          </td>
+                        ))}
+                      </tr>
+                      {/* 历史版本行 */}
+                      {doc.isExpanded && doc.historyVersions && doc.historyVersions.length > 0 && (
+                        <>
+                          {doc.historyVersions.map((historyDoc) => renderHistoryRow(historyDoc, doc))}
+                        </>
+                      )}
+                      {/* 正在加载历史版本 */}
+                      {doc.isExpanded && loadingHistory.has(doc.id) && (
+                        <tr key={`loading-${doc.id}`} className="history-row">
+                          <td colSpan={columns.length} className="px-4 py-3">
+                            <div className="version-loading">
+                              <i className="ri-loader-4-line"></i>
+                              加载历史版本中...
+                            </div>
+                          </td>
+                        </tr>
+                      )}
+                    </>
+                  ))}
+                </tbody>
+              </table>
             )}
           </div>
           
diff --git a/app/routes/documents.upload.tsx b/app/routes/documents.upload.tsx
deleted file mode 100644
index 9a7a88c..0000000
--- a/app/routes/documents.upload.tsx
+++ /dev/null
@@ -1,632 +0,0 @@
-import { useState, useRef, useCallback } from "react";
-import { type ActionFunctionArgs, type MetaFunction, json } from "@remix-run/node";
-import { Form, useActionData, useNavigation, useSubmit } from "@remix-run/react";
-import { Card } from "~/components/ui/Card";
-import { Button } from "~/components/ui/Button";
-import { Alert } from "~/components/ui/Alert";
-import { UploadArea, type UploadAreaRef } from "~/components/ui/UploadArea";
-import { FileProgress } from "~/components/ui/FileProgress";
-import { FileTag } from "~/components/ui/FileTag";
-import documentUploadStyles from "~/styles/pages/document-upload.css?url";
-
-export const links = () => [
-  { rel: "stylesheet", href: documentUploadStyles }
-];
-
-export const meta: MetaFunction = () => {
-  return [
-    { title: "上传文档 - 中国烟草AI合同及卷宗审核系统" },
-    { name: "description", content: "上传文档进行AI审核" }
-  ];
-};
-
-export const handle = {
-  breadcrumb: "上传文档"
-};
-
-// 模拟API支持的文件类型
-const SUPPORTED_FILE_TYPES = [
-  { id: "1", name: "销售合同" },
-  { id: "2", name: "采购合同" },
-  { id: "3", name: "专卖许可证" },
-  { id: "4", name: "行政处罚决定书" },
-  { id: "5", name: "承包协议" }
-];
-
-// 模拟API支持的存储类型
-const STORAGE_TYPES = [
-  { id: "minio", name: "MinIO对象存储" },
-  { id: "local", name: "本地文件系统" },
-  { id: "s3", name: "Amazon S3" }
-];
-
-// 文件上传完成后的操作选项
-const AFTER_UPLOAD_OPTIONS = [
-  { id: "list", name: "返回文档列表" },
-  { id: "stay", name: "留在当前页面" },
-  { id: "audit", name: "立即开始审核" }
-];
-
-// 定义接口
-interface UploadedFile {
-  id: string;
-  name: string;
-  size: number;
-  status: "waiting" | "uploading" | "success" | "error";
-  progress: number;
-  error?: string;
-  newName?: string;
-  type: string;
-}
-
-interface ActionData {
-  success?: boolean;
-  error?: string;
-  files?: UploadedFile[];
-}
-
-// Action函数处理表单提交
-export const action = async ({ request }: ActionFunctionArgs) => {
-  // 在实际应用中，这里应该处理文件上传逻辑
-  // 例如使用FormData API获取文件并调用后端API
-  
-  try {
-    const formData = await request.formData();
-    const docType = formData.get("docType") as string;
-    const docNumber = formData.get("docNumber") as string;
-    const docRemark = formData.get("docRemark") as string;
-    const isTestDocument = formData.get("isTestDocument") === "true";
-    const storageType = formData.get("storageType") as string;
-    const afterUpload = formData.get("afterUpload") as string;
-    
-    // 在真实情况下，这里将处理文件上传
-    // 由于Remix在服务器端不直接处理文件，我们将在客户端处理文件上传
-    // 然后将文件信息发送给服务器
-    
-    // 模拟处理过程
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    
-    return json<ActionData>({
-      success: true,
-      files: [] // 服务器处理的文件列表将返回这里
-    });
-  } catch (error) {
-    console.error("Upload error:", error);
-    return json<ActionData>(
-      { 
-        success: false, 
-        error: error instanceof Error ? error.message : "文件上传过程中发生错误" 
-      },
-      { status: 400 }
-    );
-  }
-};
-
-// 格式化文件大小
-function formatFileSize(bytes: number): string {
-  if (bytes === 0) return "0 Bytes";
-  
-  const k = 1024;
-  const sizes = ["Bytes", "KB", "MB", "GB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  
-  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
-}
-
-// 获取文件扩展名
-function getFileExtension(filename: string): string {
-  return filename.split('.').pop()?.toLowerCase() || "";
-}
-
-// 检查文件类型是否支持
-function isFileTypeSupported(filename: string): boolean {
-  const ext = getFileExtension(filename);
-  return ["pdf", "doc", "docx", "txt"].includes(ext);
-}
-
-export default function DocumentUpload() {
-  const actionData = useActionData<typeof action>();
-  const navigation = useNavigation();
-  const submit = useSubmit();
-  const uploading = navigation.state === "submitting";
-  
-  const [files, setFiles] = useState<UploadedFile[]>([]);
-  const [showAdvancedOptions, setShowAdvancedOptions] = useState(false);
-  const [isTestDocument, setIsTestDocument] = useState(false);
-  const [uploadComplete, setUploadComplete] = useState(false);
-  const [selectedFileIds, setSelectedFileIds] = useState<string[]>([]);
-  
-  const uploadAreaRef = useRef<UploadAreaRef>(null);
-  const formRef = useRef<HTMLFormElement>(null);
-  
-  // 处理文件选择
-  const handleFilesSelected = useCallback((fileList: FileList) => {
-    const newFiles: UploadedFile[] = [];
-    
-    Array.from(fileList).forEach(file => {
-      // 检查文件类型
-      if (!isFileTypeSupported(file.name)) {
-        alert(`不支持的文件类型: ${file.name}\n请上传PDF、DOC、DOCX或TXT格式文件`);
-        return;
-      }
-      
-      // 检查文件大小
-      if (file.size > 50 * 1024 * 1024) { // 50MB
-        alert(`文件过大: ${file.name}\n文件大小不能超过50MB`);
-        return;
-      }
-      
-      // 检查是否已添加
-      const isDuplicate = files.some(f => f.name === file.name && f.size === file.size);
-      if (isDuplicate) {
-        alert(`文件已添加: ${file.name}`);
-        return;
-      }
-      
-      // 添加新文件
-      newFiles.push({
-        id: `file-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
-        name: file.name,
-        size: file.size,
-        status: "waiting",
-        progress: 0,
-        type: getFileExtension(file.name)
-      });
-    });
-    
-    setFiles(prev => [...prev, ...newFiles]);
-    // 重置文件输入，允许再次选择相同文件
-    uploadAreaRef.current?.resetFileInput();
-  }, [files]);
-  
-  // 移除文件
-  const removeFile = useCallback((fileId: string) => {
-    setFiles(prev => prev.filter(file => file.id !== fileId));
-    setSelectedFileIds(prev => prev.filter(id => id !== fileId));
-  }, []);
-  
-  // 批量删除文件
-  const removeSelectedFiles = useCallback(() => {
-    if (selectedFileIds.length === 0) return;
-    
-    if (confirm(`确定要删除选中的 ${selectedFileIds.length} 个文件吗？`)) {
-      setFiles(prev => prev.filter(file => !selectedFileIds.includes(file.id)));
-      setSelectedFileIds([]);
-    }
-  }, [selectedFileIds]);
-  
-  // 清空文件列表
-  const clearAllFiles = useCallback(() => {
-    if (files.length === 0) return;
-    
-    if (confirm('确定要清空文件列表吗？')) {
-      setFiles([]);
-      setSelectedFileIds([]);
-    }
-  }, [files.length]);
-  
-  // 切换文件选择
-  const toggleFileSelection = useCallback((fileId: string, selected: boolean) => {
-    if (selected) {
-      setSelectedFileIds(prev => [...prev, fileId]);
-    } else {
-      setSelectedFileIds(prev => prev.filter(id => id !== fileId));
-    }
-  }, []);
-  
-  // 更新文件名
-  const updateFileName = useCallback((fileId: string, newName: string) => {
-    setFiles(prev => 
-      prev.map(file => 
-        file.id === fileId 
-          ? { ...file, newName: newName + '.' + getFileExtension(file.name) }
-          : file
-      )
-    );
-  }, []);
-  
-  // 提交表单
-  const handleSubmit = useCallback((event: React.FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    
-    const form = event.currentTarget;
-    const docType = form.docType.value;
-    
-    // 表单验证
-    if (!docType) {
-      alert('请选择文档类型');
-      return;
-    }
-    
-    if (files.length === 0) {
-      alert('请至少上传一个文档');
-      return;
-    }
-    
-    // 创建FormData对象
-    const formData = new FormData(form);
-    formData.append("isTestDocument", isTestDocument.toString());
-    
-    // 在实际应用中，这里应该处理文件上传
-    // 如果Remix不能直接处理文件上传，可以考虑使用预签名URL或其他方法
-    // 这里我们模拟文件上传进度
-    simulateUpload();
-    
-    // 提交表单
-    submit(formData, { method: "post", encType: "multipart/form-data" });
-  }, [files.length, isTestDocument, submit]);
-  
-  // 模拟文件上传进度
-  const simulateUpload = useCallback(() => {
-    const updatedFiles = [...files];
-    
-    // 设置所有文件为上传中状态
-    updatedFiles.forEach(file => {
-      file.status = "uploading";
-      file.progress = 0;
-    });
-    
-    setFiles(updatedFiles);
-    
-    // 模拟进度更新
-    const interval = setInterval(() => {
-      setFiles(prevFiles => {
-        const newFiles = [...prevFiles];
-        let allComplete = true;
-        
-        newFiles.forEach(file => {
-          if (file.status === "uploading") {
-            // 增加进度
-            file.progress += Math.random() * 10;
-            
-            if (file.progress >= 100) {
-              file.progress = 100;
-              
-              // 模拟有10%概率上传失败
-              if (Math.random() > 0.9) {
-                file.status = "error";
-                file.error = "上传失败，请重试";
-              } else {
-                file.status = "success";
-              }
-            } else {
-              allComplete = false;
-            }
-          }
-        });
-        
-        // 如果所有文件都完成了，停止定时器
-        if (allComplete) {
-          clearInterval(interval);
-          setTimeout(() => {
-            // 检查是否有文件上传错误
-            const hasErrors = newFiles.some(file => file.status === "error");
-            if (!hasErrors) {
-              setUploadComplete(true);
-            }
-          }, 1000);
-        }
-        
-        return newFiles;
-      });
-    }, 200);
-  }, [files]);
-  
-  // 重新上传文件
-  const retryUpload = useCallback((fileId: string) => {
-    setFiles(prev => 
-      prev.map(file => 
-        file.id === fileId 
-          ? { ...file, status: "uploading", progress: 0, error: undefined }
-          : file
-      )
-    );
-    
-    // 模拟重新上传
-    setTimeout(() => {
-      setFiles(prev => 
-        prev.map(file => {
-          if (file.id === fileId) {
-            const success = Math.random() > 0.1;
-            return { 
-              ...file, 
-              status: success ? "success" : "error",
-              progress: 100,
-              error: success ? undefined : "上传失败，请重试"
-            };
-          }
-          return file;
-        })
-      );
-    }, 2000);
-  }, []);
-  
-  // 重置表单，继续上传
-  const resetForm = useCallback(() => {
-    setFiles([]);
-    setUploadComplete(false);
-    setSelectedFileIds([]);
-    formRef.current?.reset();
-  }, []);
-  
-  return (
-    <div className="document-upload-page">
-      <div className="page-header">
-        <h2 className="page-title">上传文档</h2>
-        <div>
-          <Button to="/documents" type="default" className="mr-2">
-            <i className="ri-arrow-left-line"></i> 返回
-          </Button>
-          <Button
-            type="primary"
-            disabled={files.length === 0 || uploading}
-            onClick={() => formRef.current?.requestSubmit()}
-          >
-            <i className="ri-upload-2-line"></i> 开始上传
-          </Button>
-        </div>
-      </div>
-      
-      <Card>
-        {!uploadComplete ? (
-          <Form ref={formRef} method="post" onSubmit={handleSubmit} encType="multipart/form-data">
-            <div className="form-grid">
-              <div className="form-group">
-                <label className="form-label" htmlFor="docType">
-                  文档类型 <span className="text-red-500">*</span>
-                </label>
-                <select 
-                  id="docType" 
-                  name="docType" 
-                  className="form-select w-full" 
-                  required
-                >
-                  <option value="">请选择文档类型</option>
-                  {SUPPORTED_FILE_TYPES.map(type => (
-                    <option key={type.id} value={type.id}>
-                      {type.name}
-                    </option>
-                  ))}
-                </select>
-                <div className="form-tip">不同文档类型应用不同的评查规则</div>
-              </div>
-              
-              <div className="form-group">
-                <label className="form-label" htmlFor="docNumber">
-                  文档编号
-                </label>
-                <input
-                  type="text"
-                  id="docNumber"
-                  name="docNumber"
-                  className="form-input w-full"
-                  placeholder="请输入合同编号、许可证号等"
-                />
-                <div className="form-tip">如无编号可留空，系统将自动识别</div>
-              </div>
-            </div>
-            
-            <div className="form-group">
-              <label className="form-label" htmlFor="docRemark">
-                备注信息
-              </label>
-              <textarea
-                id="docRemark"
-                name="docRemark"
-                className="form-textarea w-full"
-                placeholder="可输入文档的相关描述或备注信息"
-                rows={2}
-              ></textarea>
-            </div>
-            
-            <div className="form-group">
-              <label className="form-label">
-                上传文档 <span className="text-red-500">*</span>
-              </label>
-              
-              <UploadArea
-                ref={uploadAreaRef}
-                onFilesSelected={handleFilesSelected}
-                accept=".pdf,.doc,.docx,.txt"
-                multiple={true}
-                icon="ri-upload-cloud-line"
-                mainText="拖拽文件到此处或点击上传"
-                tipText="支持 PDF、DOC、DOCX、TXT 格式文档，单个文件大小不超过50MB"
-                disabled={uploading}
-              />
-              
-              <div className="switch-container">
-                <label className="switch">
-                  <input
-                    type="checkbox"
-                    checked={isTestDocument}
-                    onChange={e => setIsTestDocument(e.target.checked)}
-                  />
-                  <span className="slider"></span>
-                </label>
-                <span>标记为测试文档（不计入正式统计）</span>
-              </div>
-              
-              {files.length > 0 && (
-                <div className="batch-actions">
-                  <div>
-                    <span className="text-sm">已选择 {selectedFileIds.length} 个文件</span>
-                  </div>
-                  <div>
-                    <Button 
-                      type="default" 
-                      size="small" 
-                      className="mr-2"
-                      onClick={removeSelectedFiles}
-                      disabled={selectedFileIds.length === 0 || uploading}
-                    >
-                      <i className="ri-delete-bin-line"></i> 删除选中
-                    </Button>
-                    <Button 
-                      type="default" 
-                      size="small"
-                      onClick={clearAllFiles}
-                      disabled={files.length === 0 || uploading}
-                    >
-                      <i className="ri-close-circle-line"></i> 清空列表
-                    </Button>
-                  </div>
-                </div>
-              )}
-              
-              <div className="file-list">
-                {files.map(file => (
-                  <div key={file.id} className="file-item">
-                    <input
-                      type="checkbox"
-                      checked={selectedFileIds.includes(file.id)}
-                      onChange={e => toggleFileSelection(file.id, e.target.checked)}
-                      disabled={uploading || file.status === "uploading"}
-                      className="mr-3"
-                    />
-                    
-                    <FileTag
-                      extension={getFileExtension(file.name)}
-                      size="lg"
-                      className="mr-3"
-                    />
-                    
-                    <div className="file-info">
-                      <div className="file-name flex items-center">
-                        <span>{file.newName || file.name}</span>
-                        {file.status !== "uploading" && (
-                          <button
-                            type="button"
-                            className="ml-2 text-primary text-sm"
-                            onClick={() => {
-                              const fileName = file.name;
-                              const nameWithoutExt = fileName.substring(0, fileName.lastIndexOf('.'));
-                              const newName = prompt('编辑文件名', nameWithoutExt);
-                              if (newName) {
-                                updateFileName(file.id, newName);
-                              }
-                            }}
-                            disabled={uploading}
-                          >
-                            <i className="ri-edit-line"></i>
-                          </button>
-                        )}
-                      </div>
-                      
-                      <div className="file-meta">
-                        <span className="file-size">{formatFileSize(file.size)}</span>
-                        <span className={`file-status ${file.status === "error" ? "text-red-500" : ""}`}>
-                          {file.status === "waiting" && "等待上传"}
-                          {file.status === "uploading" && "上传中..."}
-                          {file.status === "success" && "上传成功"}
-                          {file.status === "error" && (
-                            <>
-                              {file.error}
-                              <button
-                                type="button"
-                                className="ml-2 text-primary text-xs"
-                                onClick={() => retryUpload(file.id)}
-                              >
-                                <i className="ri-refresh-line"></i> 重试
-                              </button>
-                            </>
-                          )}
-                        </span>
-                      </div>
-                      
-                      <div className="progress-bar">
-                        <div className="progress-bar-inner" style={{ width: `${file.progress}%` }}></div>
-                      </div>
-                    </div>
-                    
-                    <div className="file-actions">
-                      <Button
-                        type="text"
-                        size="small"
-                        className="text-red-500"
-                        onClick={() => removeFile(file.id)}
-                        disabled={uploading || file.status === "uploading"}
-                        title="删除文件"
-                      >
-                        <i className="ri-delete-bin-line"></i>
-                      </Button>
-                    </div>
-                  </div>
-                ))}
-              </div>
-            </div>
-            
-            <div className="advanced-options">
-              <div 
-                className={`advanced-options-toggle ${showAdvancedOptions ? 'open' : ''}`}
-                onClick={() => setShowAdvancedOptions(!showAdvancedOptions)}
-              >
-                <span>高级上传设置</span>
-                <i className="ri-arrow-down-s-line"></i>
-              </div>
-              
-              <div 
-                className="advanced-options-content" 
-                style={{ display: showAdvancedOptions ? 'block' : 'none' }}
-              >
-                <div className="grid grid-cols-2 gap-4">
-                  <div className="form-group">
-                    <label className="form-label" htmlFor="storageType">存储方式</label>
-                    <select
-                      id="storageType"
-                      name="storageType"
-                      className="form-select w-full"
-                      defaultValue="minio"
-                    >
-                      {STORAGE_TYPES.map(type => (
-                        <option key={type.id} value={type.id}>
-                          {type.name}
-                        </option>
-                      ))}
-                    </select>
-                    <div className="form-tip">选择文档的存储位置</div>
-                  </div>
-                  
-                  <div className="form-group">
-                    <label className="form-label" htmlFor="afterUpload">上传后操作</label>
-                    <select
-                      id="afterUpload"
-                      name="afterUpload"
-                      className="form-select w-full"
-                      defaultValue="list"
-                    >
-                      {AFTER_UPLOAD_OPTIONS.map(option => (
-                        <option key={option.id} value={option.id}>
-                          {option.name}
-                        </option>
-                      ))}
-                    </select>
-                    <div className="form-tip">上传完成后自动执行的操作</div>
-                  </div>
-                </div>
-              </div>
-            </div>
-          </Form>
-        ) : (
-          <div className="upload-complete-actions" style={{ display: "block" }}>
-            <Alert type="success" className="mb-4">
-              所有文件上传成功！
-            </Alert>
-            
-            <div>
-              <Button type="default" className="mr-2" onClick={resetForm}>
-                <i className="ri-add-line"></i> 继续上传
-              </Button>
-              <Button to="/documents" type="default" className="mr-2">
-                <i className="ri-list-check-line"></i> 查看文档列表
-              </Button>
-              <Button to="/documents/1?action=audit" type="primary">
-                <i className="ri-play-circle-line"></i> 开始审核
-              </Button>
-            </div>
-          </div>
-        )}
-      </Card>
-    </div>
-  );
-}
diff --git a/app/routes/examples/TooltipExample.tsx b/app/routes/examples/TooltipExample.tsx
deleted file mode 100644
index 6c8c6ac..0000000
--- a/app/routes/examples/TooltipExample.tsx
+++ /dev/null
@@ -1,236 +0,0 @@
-import { Tooltip } from '../../components/ui/Tooltip';
-
-/**
- * Tooltip 组件示例
- * 展示不同主题、位置和风格的提示框
- */
-export function TooltipExample() {
-  return (
-    <div className="tooltip-examples p-4">
-      <h2 className="text-lg font-bold mb-4">Tooltip 组件示例</h2>
-      
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
-        {/* 基础提示框 */}
-        <div className="example-section">
-          <h3 className="text-base font-semibold mb-2">基础提示框</h3>
-          <div className="flex space-x-4 mb-4">
-            <Tooltip content="这是一个基础提示框">
-              <button className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300">
-                鼠标悬停
-              </button>
-            </Tooltip>
-            
-            <Tooltip content="点击显示的提示框" trigger="click">
-              <button className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300">
-                点击查看
-              </button>
-            </Tooltip>
-          </div>
-        </div>
-        
-        {/* 不同位置 */}
-        <div className="example-section">
-          <h3 className="text-base font-semibold mb-2">不同位置</h3>
-          <div className="flex space-x-4 mb-4">
-            <Tooltip content="顶部提示" placement="top">
-              <button className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300">
-                顶部
-              </button>
-            </Tooltip>
-            
-            <Tooltip content="底部提示" placement="bottom">
-              <button className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300">
-                底部
-              </button>
-            </Tooltip>
-            
-            <Tooltip content="左侧提示" placement="left">
-              <button className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300">
-                左侧
-              </button>
-            </Tooltip>
-            
-            <Tooltip content="右侧提示" placement="right">
-              <button className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300">
-                右侧
-              </button>
-            </Tooltip>
-          </div>
-        </div>
-        
-        {/* 不同主题 */}
-        <div className="example-section">
-          <h3 className="text-base font-semibold mb-2">不同主题</h3>
-          <div className="flex flex-wrap gap-2">
-            <Tooltip content="深色主题" theme="dark">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                深色
-              </span>
-            </Tooltip>
-            
-            <Tooltip content="浅色主题" theme="light">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                浅色
-              </span>
-            </Tooltip>
-            
-            <Tooltip content="主题色" theme="primary">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                主题色
-              </span>
-            </Tooltip>
-            
-            <Tooltip content="成功提示" theme="success">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                成功
-              </span>
-            </Tooltip>
-            
-            <Tooltip content="警告提示" theme="warning">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                警告
-              </span>
-            </Tooltip>
-            
-            <Tooltip content="错误提示" theme="error">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                错误
-              </span>
-            </Tooltip>
-            
-            <Tooltip content="信息提示" theme="info">
-              <span className="px-3 py-1 border border-gray-300 rounded cursor-default">
-                信息
-              </span>
-            </Tooltip>
-          </div>
-        </div>
-        
-        {/* 富文本提示框 */}
-        <div className="example-section">
-          <h3 className="text-base font-semibold mb-2">富文本提示框</h3>
-          <div className="flex space-x-4">
-            <Tooltip
-              content={
-                <div>
-                  <div className="flex items-center mb-1">
-                    <span className="w-24 text-gray-500">CPU使用率:</span>
-                    <span className="text-green-500 font-medium">32%</span>
-                  </div>
-                  <div className="flex items-center mb-1">
-                    <span className="w-24 text-gray-500">内存使用率:</span>
-                    <span className="text-yellow-500 font-medium">76%</span>
-                  </div>
-                  <div className="flex items-center">
-                    <span className="w-24 text-gray-500">磁盘空间:</span>
-                    <span className="text-blue-500 font-medium">245GB/500GB</span>
-                  </div>
-                </div>
-              }
-              theme="light"
-              rich={true}
-              header="系统性能报告"
-              footer="更新时间: 2023-10-15 15:30:42"
-              showArrow={true}
-            >
-              <button className="px-3 py-1 bg-blue-500 text-white rounded hover:bg-blue-600">
-                性能分析
-              </button>
-            </Tooltip>
-            
-            <Tooltip
-              content={
-                <div>
-                  <div className="flex items-center justify-between mb-1">
-                    <span>本月销售额:</span>
-                    <span className="text-green-400 font-medium">¥258,432</span>
-                  </div>
-                  <div className="flex items-center justify-between mb-1">
-                    <span>环比增长:</span>
-                    <span className="text-green-400 font-medium">+15.8%</span>
-                  </div>
-                  <div className="flex items-center justify-between">
-                    <span>销售热点:</span>
-                    <span className="text-yellow-400 font-medium">电子产品</span>
-                  </div>
-                </div>
-              }
-              theme="dark"
-              rich={true}
-              header="销售数据分析"
-              footer="数据来源: 销售管理系统"
-              placement="bottom"
-            >
-              <button className="px-3 py-1 bg-green-500 text-white rounded hover:bg-green-600">
-                销售趋势
-              </button>
-            </Tooltip>
-          </div>
-        </div>
-        
-        {/* 条件渲染示例 */}
-        <div className="example-section">
-          <h3 className="text-base font-semibold mb-2">状态提示示例</h3>
-          <div className="flex space-x-4">
-            <Tooltip
-              content="优秀：得分在90分以上"
-              theme="success"
-            >
-              <span className="text-green-500 font-bold px-2">95</span>
-            </Tooltip>
-            
-            <Tooltip
-              content="良好：得分在60-90分之间"
-              theme="warning"
-            >
-              <span className="text-yellow-500 px-2">75</span>
-            </Tooltip>
-            
-            <Tooltip
-              content="不及格：得分低于60分"
-              theme="error"
-            >
-              <span className="text-red-500 px-2">45</span>
-            </Tooltip>
-          </div>
-        </div>
-        
-        {/* 自定义样式示例 */}
-        <div className="example-section">
-          <h3 className="text-base font-semibold mb-2">自定义样式</h3>
-          <div className="flex space-x-4">
-            <Tooltip
-              content="带有自定义宽度的提示框"
-              maxWidth={150}
-            >
-              <span className="border-b border-dotted border-gray-500 cursor-help">
-                自定义宽度
-              </span>
-            </Tooltip>
-            
-            <Tooltip
-              content="没有箭头的提示框"
-              showArrow={false}
-              theme="primary"
-            >
-              <span className="border-b border-dotted border-blue-500 cursor-help">
-                无箭头
-              </span>
-            </Tooltip>
-            
-            <Tooltip
-              content="自定义类名"
-              className="custom-tooltip"
-            >
-              <span className="border-b border-dotted border-purple-500 cursor-help text-purple-500">
-                自定义类名
-              </span>
-            </Tooltip>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-export default TooltipExample; 
\ No newline at end of file
diff --git a/app/routes/examples/message-modal.tsx b/app/routes/examples/message-modal.tsx
deleted file mode 100644
index 7a8e958..0000000
--- a/app/routes/examples/message-modal.tsx
+++ /dev/null
@@ -1,204 +0,0 @@
-import { useState } from 'react';
-import { MessageModal, messageService, MessageModalProvider } from '~/components/ui/MessageModal';
-import type { MessageType } from '~/components/ui/MessageModal';
-import { LinksFunction } from '@remix-run/node';
-import messageModalStyles from '~/styles/components/message-modal.css?url';
-
-export const links: LinksFunction = () => [
-  { rel: "stylesheet", href: messageModalStyles },
-];
-
-export default function MessageModalExample() {
-  const [isModalOpen, setIsModalOpen] = useState(false);
-  const [modalType, setModalType] = useState<MessageType>('info');
-  const [modalTitle, setModalTitle] = useState('');
-  const [modalMessage, setModalMessage] = useState('');
-  const [withConfirm, setWithConfirm] = useState(false);
-  const [autoClose, setAutoClose] = useState(false);
-  
-  // 打开普通模态框
-  const openModal = (type: MessageType, title: string, message: string) => {
-    setModalType(type);
-    setModalTitle(title);
-    setModalMessage(message);
-    setIsModalOpen(true);
-  };
-  
-  // 打开各类型的服务提示框
-  const showSuccessMessage = () => {
-    messageService.success('操作成功完成！', { 
-      title: '成功提示', 
-      autoClose: true 
-    });
-  };
-  
-  const showErrorMessage = () => {
-    messageService.error('操作过程中发生错误，请重试。', { 
-      title: '错误提示' 
-    });
-  };
-  
-  const showWarningMessage = () => {
-    messageService.warning('此操作可能产生不可逆转的结果。', { 
-      title: '警告提示',
-      onConfirm: () => {
-        messageService.success('您已确认继续操作')
-      },
-      confirmText: '继续操作',
-      cancelText: '取消'
-    });
-  };
-  
-  const showInfoMessage = () => {
-    messageService.info('系统将于今晚10点进行升级维护。', { 
-      title: '通知',
-      autoClose: true,
-      autoCloseDelay: 5000
-    });
-  };
-  
-  const showCustomMessage = () => {
-    messageService.show({
-      title: '自定义消息',
-      message: '这是一个带有自定义内容的消息',
-      type: 'info',
-      confirmText: '了解',
-      children: (
-        <div style={{ 
-          padding: '10px', 
-          backgroundColor: '#f0f0f0', 
-          borderRadius: '6px',
-          marginTop: '10px' 
-        }}>
-          <p>这里可以放置更复杂的自定义内容。</p>
-          <div style={{ 
-            display: 'flex', 
-            alignItems: 'center', 
-            marginTop: '10px' 
-          }}>
-            <i className="ri-information-line" style={{ marginRight: '8px', color: '#1890ff' }}></i>
-            <span>比如详细的操作说明或其他信息。</span>
-          </div>
-        </div>
-      )
-    });
-  };
-  
-  // 处理确认
-  const handleConfirm = () => {
-    messageService.success('您点击了确认按钮！', { autoClose: true });
-    setIsModalOpen(false);
-  };
-  
-  return (
-    <MessageModalProvider>
-      <div className="container mx-auto p-6">
-        <h1 className="text-2xl font-bold mb-6">消息模态框示例</h1>
-        
-        <div className="bg-white rounded-lg p-6 shadow-md mb-8">
-          <h2 className="text-xl font-semibold mb-4">基本用法</h2>
-          <p className="mb-4">您可以直接使用MessageModal组件来控制模态框的显示和隐藏。</p>
-          
-          <div className="flex flex-wrap gap-3 mb-6">
-            <button 
-              className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
-              onClick={() => openModal('info', '信息提示', '这是一个普通的信息提示框')}
-            >
-              信息提示框
-            </button>
-            <button 
-              className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600"
-              onClick={() => openModal('success', '成功提示', '操作已成功完成')}
-            >
-              成功提示框
-            </button>
-            <button 
-              className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
-              onClick={() => openModal('error', '错误提示', '操作失败，请检查输入')}
-            >
-              错误提示框
-            </button>
-            <button 
-              className="px-4 py-2 bg-yellow-500 text-white rounded hover:bg-yellow-600"
-              onClick={() => openModal('warning', '警告提示', '此操作将删除数据，是否继续？')}
-            >
-              警告提示框
-            </button>
-          </div>
-          
-          <div className="flex flex-wrap gap-4 mb-4">
-            <label className="flex items-center">
-              <input 
-                type="checkbox"
-                checked={withConfirm}
-                onChange={(e) => setWithConfirm(e.target.checked)}
-                className="mr-2"
-              />
-              添加确认按钮
-            </label>
-            
-            <label className="flex items-center">
-              <input 
-                type="checkbox"
-                checked={autoClose}
-                onChange={(e) => setAutoClose(e.target.checked)}
-                className="mr-2"
-              />
-              自动关闭 (3秒)
-            </label>
-          </div>
-          
-          <MessageModal
-            isOpen={isModalOpen}
-            onClose={() => setIsModalOpen(false)}
-            title={modalTitle}
-            message={modalMessage}
-            type={modalType}
-            autoClose={autoClose}
-            onConfirm={withConfirm ? handleConfirm : undefined}
-            confirmText={withConfirm ? "确认" : "我知道了"}
-            cancelText="取消"
-          />
-        </div>
-        
-        <div className="bg-white rounded-lg p-6 shadow-md mb-8">
-          <h2 className="text-xl font-semibold mb-4">全局消息服务</h2>
-          <p className="mb-4">使用messageService可以在任何组件中方便地显示消息提示，而无需手动管理状态。</p>
-          
-          <div className="flex flex-wrap gap-3">
-            <button 
-              className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600"
-              onClick={showSuccessMessage}
-            >
-              成功提示 (自动关闭)
-            </button>
-            <button 
-              className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
-              onClick={showErrorMessage}
-            >
-              错误提示
-            </button>
-            <button 
-              className="px-4 py-2 bg-yellow-500 text-white rounded hover:bg-yellow-600"
-              onClick={showWarningMessage}
-            >
-              警告提示 (带确认)
-            </button>
-            <button 
-              className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
-              onClick={showInfoMessage}
-            >
-              信息提示 (5秒后关闭)
-            </button>
-            <button 
-              className="px-4 py-2 bg-purple-500 text-white rounded hover:bg-purple-600"
-              onClick={showCustomMessage}
-            >
-              自定义内容提示
-            </button>
-          </div>
-        </div>
-      </div>
-    </MessageModalProvider>
-  );
-} 
\ No newline at end of file
diff --git a/app/routes/examples/pdfview.tsx b/app/routes/examples/pdfview.tsx
deleted file mode 100644
index 5f02fdd..0000000
--- a/app/routes/examples/pdfview.tsx
+++ /dev/null
@@ -1,192 +0,0 @@
-import React, { useEffect, useRef, useState, useCallback } from 'react';
-import { createPortal } from 'react-dom';
-import { Spin, Tooltip, Input } from 'antd';
-import {
-  LeftOutlined,
-  RightOutlined,
-  PlusCircleOutlined,
-  MinusCircleOutlined,
-  FullscreenExitOutlined,
-  FullscreenOutlined,
-  CloseCircleOutlined,
-  ExclamationCircleOutlined,
-  RotateLeftOutlined,
-  RotateRightOutlined,
-  UnorderedListOutlined,
-} from '@ant-design/icons';
-import  './index.less';
-import { Document, Page, pdfjs } from 'react-pdf';
-import pdfjsWorker from 'react-pdf/dist/esm/pdf.worker.entry';
- 
-pdfjs.GlobalWorkerOptions.workerSrc = pdfjsWorker;
- 
-const PDFView = ({
-  file,
-  parentDom,
-  onClose,
-}: {
-  file?: string | null;
-  parentDom?: HTMLDivElement | null;
-  onClose?: () => void;
-}) => {
-  const defaultWidth = 600;
-  const pageDiv = useRef<HTMLDivElement>(null);
-  const [numPages, setNumPages] = useState<number>(0);
-  const [pageNumber, setPageNumber] = useState<number>(1);
-  const [pageWidth, setPageWidth] = useState<number>(defaultWidth);
-  const [fullscreen, setFullscreen] = useState<boolean>(false);
-  const [rotation, setRotation] = useState<number>(0);
-  const [showThumbnails, setShowThumbnails] = useState<boolean>(false);
-  const [visiblePages, setVisiblePages] = useState<number[]>([1]); // 控制可见页面
- 
-  const parent = parentDom || document.body;
- 
-  // 加载 PDF 元信息，不渲染全部页面
-  const onDocumentLoadSuccess = useCallback(({ numPages }: { numPages: number }) => {
-    setNumPages(numPages);
-  }, []);
- 
-  const lastPage = () => pageNumber > 1 && setPageNumber(pageNumber - 1);
-  const nextPage = () => pageNumber < numPages && setPageNumber(pageNumber + 1);
-  const onPageNumberChange = (e: { target: { value: string } }) => {
-    let value = Math.max(1, Math.min(numPages, Number(e.target.value) || 1));
-    setPageNumber(value);
-    setVisiblePages([value]); // 只加载当前页
-  };
- 
-  const pageZoomIn = () => setPageWidth(pageWidth * 1.2);
-  const pageZoomOut = () => pageWidth > defaultWidth && setPageWidth(pageWidth * 0.8);
-  const pageFullscreen = () => {
-    setPageWidth(fullscreen ? defaultWidth : parent.offsetWidth - 50);
-    setFullscreen(!fullscreen);
-  };
- 
-  const rotateLeft = () => setRotation((prev) => (prev - 90) % 360);
-  const rotateRight = () => setRotation((prev) => (prev + 90) % 360);
-  const toggleThumbnails = () => setShowThumbnails(!showThumbnails);
- 
-  // 动态更新可见页面
-  useEffect(() => {
-    if (!showThumbnails) {
-      setVisiblePages([pageNumber]);
-    } else {
-      // 缩略图模式下限制加载数量，避免卡顿
-      const start = Math.max(1, pageNumber - 2);
-      const end = Math.min(numPages, pageNumber + 2);
-      setVisiblePages(Array.from({ length: end - start + 1 }, (_, i) => start + i));
-    }
-  }, [pageNumber, showThumbnails, numPages]);
- 
-  useEffect(() => setPageNumber(1), [file]);
-  useEffect(() => {
-    if( pageDiv.current){
-     (pageDiv.current.scrollTop = 0)
-    }
-  }, [pageNumber]);
- 
-  const renderContent=()=>(<div className='view'>
-    <div className='viewContent' >
-      <div className='pageMain' ref={pageDiv}>
-        <div className='pageContainer'>
-            <Document
-              file={file}
-              onLoadSuccess={onDocumentLoadSuccess}
-              error={
-                <div style={{ textAlign: 'center', width: defaultWidth + 'px' }}>
-                  <ExclamationCircleOutlined style={{ fontSize: '150px', color: '#fe725c', margin: '100px' }} />
-                </div>
-              }
-              loading={<div style={{ textAlign: 'center', width: defaultWidth + 'px' }}><Spin size="large" style={{ margin: '200px' }} /></div>}
-            >
-              {showThumbnails ? (
-                <div className='thumbnailContainer'>
-                  {Array.from({ length: numPages }, (_, i) => i + 1).map((page) => (
-                    <div
-                      key={page}
-                      className='thumbnail'
-                      onClick={() => {
-                        setPageNumber(page);
-                        setShowThumbnails(false);
-                      }}
-                    >
-                      {visiblePages.includes(page) ? (
-                        <Page
-                          pageNumber={page}
-                          width={150}
-                          rotate={rotation}
-                          loading={<Spin />}
-                          renderTextLayer={false} // 禁用文本层，提升性能
-                          renderAnnotationLayer={false} // 禁用注释层
-                        />
-                      ) : (
-                        <div className='thumbnailPlaceholder'>第 {page} 页</div>
-                      )}
-                      <span>第 {page} 页</span>
-                    </div>
-                  ))}
-                </div>
-              ) : (
-                <Page
-                  pageNumber={pageNumber}
-                  width={pageWidth}
-                  rotate={rotation}
-                  loading={<Spin size="large" />}
-                  renderTextLayer={false} // 禁用文本层
-                  renderAnnotationLayer={false} // 禁用注释层
-                  error={() => setPageNumber(1)}
-                />
-              )}
-            </Document>
-        </div>
-      </div>
-      <div className='pageBar'>
-        <div className='pageTool'>
-          <Tooltip title={pageNumber === 1 ? '已是第一页' : '上一页'}>
-            <LeftOutlined onClick={lastPage} />
-          </Tooltip>
-          <Input
-            value={pageNumber}
-            onChange={onPageNumberChange}
-            onPressEnter={onPageNumberChange as any}
-            type="number"
-          />{' '}
-          / {numPages}
-          <Tooltip title={pageNumber === numPages ? '已是最后一页' : '下一页'}>
-            <RightOutlined onClick={nextPage} />
-          </Tooltip>
-          <Tooltip title="放大">
-            <PlusCircleOutlined onClick={pageZoomIn} />
-          </Tooltip>
-          <Tooltip title="缩小">
-            <MinusCircleOutlined onClick={pageZoomOut} />
-          </Tooltip>
-          <Tooltip title="向左旋转">
-            <RotateLeftOutlined onClick={rotateLeft} />
-          </Tooltip>
-          <Tooltip title="向右旋转">
-            <RotateRightOutlined onClick={rotateRight} />
-          </Tooltip>
-          <Tooltip title={showThumbnails ? '关闭缩略图' : '显示缩略图'}>
-            <UnorderedListOutlined onClick={toggleThumbnails} />
-          </Tooltip>
-          <Tooltip title={fullscreen ? '恢复默认' : '适合窗口'}>
-            {fullscreen ? <FullscreenExitOutlined onClick={pageFullscreen} /> : <FullscreenOutlined onClick={pageFullscreen} />}
-          </Tooltip>
-          {onClose && (
-            <Tooltip title="关闭">
-              <CloseCircleOutlined onClick={onClose} />
-            </Tooltip>
-          )}
-        </div>
-      </div>
-    </div>
-  </div>)
-  if(parentDom){
-    return renderContent()
-  }
-  return createPortal(
-    renderContent(),
-    parent,)
-};
- 
-export default PDFView;
\ No newline at end of file
diff --git a/app/routes/examples/toast.tsx b/app/routes/examples/toast.tsx
deleted file mode 100644
index fe5108b..0000000
--- a/app/routes/examples/toast.tsx
+++ /dev/null
@@ -1,164 +0,0 @@
-import { useState } from 'react';
-import { Toast, toastService } from '~/components/ui/Toast';
-import type { ToastType } from '~/components/ui/Toast';
-import { LinksFunction } from '@remix-run/node';
-import toastStyles from '~/styles/components/toast.css?url';
-
-export const links: LinksFunction = () => [
-  { rel: "stylesheet", href: toastStyles },
-];
-
-export default function ToastExample() {
-  const [isToastOpen, setIsToastOpen] = useState(false);
-  const [toastType, setToastType] = useState<ToastType>('info');
-  const [toastMessage, setToastMessage] = useState('');
-  const [autoClose, setAutoClose] = useState(true);
-  
-  // 打开普通通知
-  const openToast = (type: ToastType, message: string) => {
-    setToastType(type);
-    setToastMessage(message);
-    setIsToastOpen(true);
-  };
-  
-  // 使用服务显示不同类型通知
-  const showSuccessToast = () => {
-    toastService.success('操作成功完成！');
-  };
-  
-  const showErrorToast = () => {
-    toastService.error('操作过程中发生错误，请重试。');
-  };
-  
-  const showWarningToast = () => {
-    toastService.warning('此操作可能产生不可逆转的结果。');
-  };
-  
-  const showInfoToast = () => {
-    toastService.info('系统将于今晚10点进行升级维护。');
-  };
-  
-  // 显示多行文本的长通知
-  const showLongToast = () => {
-    toastService.info('这是一个具有很长内容的通知，将自动换行以适应容器宽度，并且最多显示三行，超出部分会被截断。系统会自动处理长文本的换行和截断，确保显示效果一致。');
-  };
-  
-  // 短时间内显示多个通知
-  const showMultipleToasts = () => {
-    toastService.success('第一条通知');
-    setTimeout(() => {
-      toastService.info('第二条通知');
-    }, 300);
-    setTimeout(() => {
-      toastService.warning('第三条通知');
-    }, 600);
-    setTimeout(() => {
-      toastService.error('第四条通知');
-    }, 900);
-  };
-  
-  return (
-    <div className="container mx-auto p-6">
-      <h1 className="text-2xl font-bold mb-6">轻量级顶部通知示例</h1>
-      
-      <div className="bg-white rounded-lg p-6 shadow-md mb-8">
-        <h2 className="text-xl font-semibold mb-4">基本用法</h2>
-        <p className="mb-4">您可以直接使用Toast组件来控制通知的显示和隐藏。</p>
-        
-        <div className="flex flex-wrap gap-3 mb-6">
-          <button 
-            className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
-            onClick={() => openToast('info', '这是一个信息通知')}
-          >
-            信息通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600"
-            onClick={() => openToast('success', '操作已成功完成')}
-          >
-            成功通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
-            onClick={() => openToast('error', '操作失败，请检查输入')}
-          >
-            错误通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-yellow-500 text-white rounded hover:bg-yellow-600"
-            onClick={() => openToast('warning', '请注意，这是一个警告通知')}
-          >
-            警告通知
-          </button>
-        </div>
-        
-        <div className="mb-4">
-          <label className="flex items-center">
-            <input 
-              type="checkbox"
-              checked={autoClose}
-              onChange={(e) => setAutoClose(e.target.checked)}
-              className="mr-2"
-            />
-            自动关闭 (3秒)
-          </label>
-        </div>
-        
-        <Toast
-          isOpen={isToastOpen}
-          onClose={() => setIsToastOpen(false)}
-          message={toastMessage}
-          type={toastType}
-          autoClose={autoClose}
-        />
-      </div>
-      
-      <div className="bg-white rounded-lg p-6 shadow-md mb-8">
-        <h2 className="text-xl font-semibold mb-4">全局通知服务</h2>
-        <p className="mb-4">使用toastService可以在任何组件中方便地显示通知，而无需手动管理状态。</p>
-        
-        <div className="flex flex-wrap gap-3 mb-6">
-          <button 
-            className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600"
-            onClick={showSuccessToast}
-          >
-            成功通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
-            onClick={showErrorToast}
-          >
-            错误通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-yellow-500 text-white rounded hover:bg-yellow-600"
-            onClick={showWarningToast}
-          >
-            警告通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
-            onClick={showInfoToast}
-          >
-            信息通知
-          </button>
-        </div>
-        
-        <div className="flex flex-wrap gap-3">
-          <button 
-            className="px-4 py-2 bg-purple-500 text-white rounded hover:bg-purple-600"
-            onClick={showLongToast}
-          >
-            长文本通知
-          </button>
-          <button 
-            className="px-4 py-2 bg-pink-500 text-white rounded hover:bg-pink-600"
-            onClick={showMultipleToasts}
-          >
-            多个通知
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-} 
\ No newline at end of file
diff --git a/app/routes/home.tsx b/app/routes/home.tsx
index dc5c5d5..5bd9c8e 100644
--- a/app/routes/home.tsx
+++ b/app/routes/home.tsx
@@ -366,17 +366,17 @@ export default function Home() {
       <Card title="快捷访问" icon="ri-speed-line" className="mt-6 transition-all duration-200 hover:shadow-[0_4px_15px_rgba(0,0,0,0.1)]">
         <div className="shortcut-grid">
           <ShortcutItem icon="ri-upload-cloud-line" label="上传文件" to="/files/upload" />
-          <ShortcutItem icon="ri-file-list-3-line" label="文档列表" to="/documents" />
+          <ShortcutItem icon="ri-file-list-3-line" label="文档列表" to="/documents/list" />
           <ShortcutItem icon="ri-list-check-3" label="评查点列表" to="/rules" />
           <ShortcutItem icon="ri-folder-open-line" label="评查点分组" to="/rule-groups" />
         </div>
       </Card>
-      
+
       {/* 最近文档区域 */}
-      <Card 
-        title="最近文档" 
-        icon="ri-file-list-3-line" 
-        extra={<Button to="/documents" size="small">查看全部</Button>}
+      <Card
+        title="最近文档"
+        icon="ri-file-list-3-line"
+        extra={<Button to="/documents/list" size="small">查看全部</Button>}
         className="mt-6"
       >
         <div className="doc-list">
diff --git a/app/routes/login.tsx b/app/routes/login.tsx
index 20833a3..a561092 100644
--- a/app/routes/login.tsx
+++ b/app/routes/login.tsx
@@ -1,9 +1,10 @@
 import { useEffect, useState } from "react";
-import { useActionData, useLoaderData, Form } from "@remix-run/react";
+import { useLoaderData, useNavigate, useFetcher } from "@remix-run/react";
 import { type MetaFunction, type LoaderFunctionArgs, type ActionFunctionArgs, redirect } from "@remix-run/node";
 import { OAuthClient } from "~/api/login/oauth-client";
 import { CLIENT_OAUTH_CONFIG } from "~/config/api-config";
-import { getUserSession, getSession, simpleRootLogin } from "~/api/login/auth.server";
+import { getUserSession, getSession, createUserSession } from "~/api/login/auth.server";
+import { loginWithPassword } from "~/api/login/login-client";
 import styles from "~/styles/pages/login.css?url";
 import { toastService } from "~/components/ui";
 
@@ -18,31 +19,24 @@ export const meta: MetaFunction = () => {
   ];
 };
 
-// 加载器，获取当前会话状态
+// 加载器，获取重定向URL和错误信息
 export async function loader({ request }: LoaderFunctionArgs) {
-  const { isAuthenticated } = await getUserSession(request);
-  
-  // 如果已登录，重定向到首页
-  if (isAuthenticated) {
-    return redirect("/");
-  }
+  // ⚠️ 不再检查服务端 session 认证
+  // 认证检查改为在客户端通过 localStorage 进行
 
-  // 获取重定向URL并保存到session
+  // 获取重定向URL
   const url = new URL(request.url);
   const redirectTo = url.searchParams.get("redirect") || "/";
-  
+
   const session = await getSession(request);
-  
+
   // 读取 flash 消息（来自 callback 的错误）
   const loginError = session.get("loginError");
-  
-  session.set("redirectTo", redirectTo);
-  
+
   // 提交 session 以清除 flash 消息
   if (loginError) {
     const { sessionStorage } = await import("~/api/login/auth.server");
-    return Response.json({ 
-      isAuthenticated: false,
+    return Response.json({
       redirectTo,
       flashError: loginError
     }, {
@@ -51,65 +45,141 @@ export async function loader({ request }: LoaderFunctionArgs) {
       }
     });
   }
-  
-  return Response.json({ 
-    isAuthenticated: false,
+
+  return Response.json({
     redirectTo,
     flashError: null
   });
 }
 
-// 处理表单提交的action函数
+// 处理管理员账密登录
 export async function action({ request }: ActionFunctionArgs) {
-  const formData = await request.formData();
-  const intent = formData.get("intent");
-  const username = formData.get("username")?.toString().trim();
-  const password = formData.get("password")?.toString().trim();
+  try {
+    const formData = await request.formData();
+    const username = formData.get("username") as string;
+    const password = formData.get("password") as string;
+    const redirectTo = formData.get("redirectTo") as string || "/";
 
-  if (intent === "password_login") {
-    // 获取重定向目标
-    const session = await getSession(request);
-    const redirectTo = session.get("redirectTo") || "/";
-    
-    // 调用 simpleRootLogin 方法进行登录
-    const response = await simpleRootLogin(username || "", password || "", redirectTo);
-    
-    // 检查响应状态
-    if (response.status === 302) {
-      // 登录成功，直接返回重定向响应
-      return response;
-    } else {
-      // 登录失败，返回错误信息（不再使用URL参数）
-      const errorData = await response.json();
+    // 验证输入
+    if (!username?.trim()) {
       return Response.json({
         success: false,
-        error: errorData.error || "登录失败",
-        retryCount: errorData.retryCount || 0,
-        isLocked: errorData.isLocked || false,
-        remainingAttempts: errorData.remainingAttempts || 5
-      }, {
-        status: response.status
-      });
+        error: "请输入用户名"
+      }, { status: 400 });
     }
-  }
 
-  return null;
+    if (!password?.trim()) {
+      return Response.json({
+        success: false,
+        error: "请输入密码"
+      }, { status: 400 });
+    }
+
+    console.log("📝 [Login Action] 开始处理管理员登录:", { username });
+
+    // 调用后端登录接口
+    const response = await loginWithPassword(username.trim(), password.trim());
+
+    if (!response.success || !response.data) {
+      console.error("❌ [Login Action] 登录失败:", response.error);
+      return Response.json({
+        success: false,
+        error: response.error || "登录失败，请检查用户名和密码"
+      }, { status: 401 });
+    }
+
+    const { access_token, user_info } = response.data;
+
+    // 验证返回数据
+    if (!access_token) {
+      console.error("❌ [Login Action] 后端未返回 access_token");
+      return Response.json({
+        success: false,
+        error: "登录失败：未获取到认证令牌"
+      }, { status: 500 });
+    }
+
+    if (!user_info) {
+      console.error("❌ [Login Action] 后端未返回 user_info");
+      return Response.json({
+        success: false,
+        error: "登录失败：未获取到用户信息"
+      }, { status: 500 });
+    }
+
+    console.log("✅ [Login Action] 登录成功，准备创建 session");
+    console.log("👤 [Login Action] 用户角色:", user_info.user_role); // 应该是 "admin"
+
+    // 获取当前 URL 用于构建 callback URL
+    const url = new URL(request.url);
+
+    // 🔑 重要：将 token 和用户信息作为 URL 参数传递给客户端
+    // 复用 OAuth 登录的 callback 页面逻辑
+    const callbackUrl = new URL('/callback', url.origin);
+    callbackUrl.searchParams.set('token', access_token);
+    callbackUrl.searchParams.set('userInfo', encodeURIComponent(JSON.stringify({
+      user_id: user_info.user_id,
+      username: user_info.username,
+      nick_name: user_info.nick_name,
+      email: user_info.email,
+      phone_number: user_info.phone_number,
+      ou_id: user_info.ou_id,
+      ou_name: user_info.ou_name,
+      is_leader: user_info.is_leader,
+      user_role: user_info.user_role,
+      sub: user_info.sub
+    })));
+    callbackUrl.searchParams.set('redirectTo', redirectTo);
+
+    // ✅ 使用统一的 session 创建函数（和 OAuth 登录一样）
+    return createUserSession({
+      isAuthenticated: true,
+      userRole: user_info.user_role,
+      redirectTo: callbackUrl.toString(), // 先跳转到 callback 页面保存 token
+      frontendJWT: access_token,          // 保存到 Cookie Session
+      userInfo: {
+        user_id: user_info.user_id,
+        username: user_info.username,
+        nick_name: user_info.nick_name,
+        email: user_info.email,
+        phone_number: user_info.phone_number,
+        ou_id: user_info.ou_id,
+        ou_name: user_info.ou_name,
+        is_leader: user_info.is_leader,
+        user_role: user_info.user_role,
+        sub: user_info.sub
+      }
+    });
+
+  } catch (error) {
+    console.error("❌ [Login Action] 处理登录时发生异常:", error);
+    return Response.json({
+      success: false,
+      error: error instanceof Error ? error.message : "登录失败，请稍后重试"
+    }, { status: 500 });
+  }
 }
 
 export default function Login() {
-  const actionData = useActionData<typeof action>();
+  const navigate = useNavigate();
   const loaderData = useLoaderData<typeof loader>();
+  const fetcher = useFetcher<{ success: boolean; error?: string }>();
   const [isFlipped, setIsFlipped] = useState(false);
   const [username, setUsername] = useState("");
   const [password, setPassword] = useState("");
-  
-  // 从 actionData 或 loaderData 中获取错误信息
-  // actionData 的错误优先（来自密码登录）
-  // loaderData.flashError 次之（来自 OAuth 回调）
-  const error = actionData?.error || loaderData?.flashError;
-  const isLocked = actionData?.isLocked || false;
-  const retryCount = actionData?.retryCount || 0;
-  const remainingAttempts = actionData?.remainingAttempts || 5;
+  const [passwordLoginError, setPasswordLoginError] = useState<string | null>(null);
+
+  // 从 loaderData 中获取 OAuth 回调的错误信息
+  const oauthError = loaderData?.flashError;
+
+  // 显示的错误信息：密码登录错误优先，其次是 OAuth 错误
+  const error = passwordLoginError || oauthError;
+  const isLocked = false; // 可以从后端响应中获取
+  const retryCount = 0;
+  const remainingAttempts = 5;
+
+  // 监听 fetcher 的状态
+  const isLoading = fetcher.state === "submitting" || fetcher.state === "loading";
 
   // 处理OAuth2.0登录
   const handleOAuthLogin = () => {
@@ -148,29 +218,55 @@ export default function Login() {
 
   // 处理账号密码登录表单提交
   const handlePasswordLoginSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    // 清除之前的错误
+    setPasswordLoginError(null);
+
     // 检查账户是否被锁定
     if (isLocked) {
-      e.preventDefault();
       toastService.error("账户已被锁定，请联系管理员");
       return;
     }
-    
+
     // 客户端验证
     if (!username.trim()) {
-      e.preventDefault();
       toastService.error("请输入用户名");
       return;
     }
-    
+
     if (!password.trim()) {
-      e.preventDefault();
       toastService.error("请输入密码");
       return;
     }
-    
-    // 验证通过，让表单正常提交
+
+    console.log("📝 [Login] 提交管理员登录表单");
+
+    // ✅ 使用 fetcher 提交表单到服务端 action
+    const formData = new FormData();
+    formData.append("username", username.trim());
+    formData.append("password", password.trim());
+    formData.append("redirectTo", loaderData?.redirectTo || "/");
+
+    fetcher.submit(formData, {
+      method: "post",
+      action: "/login"
+    });
   };
 
+  // 处理 fetcher 响应
+  useEffect(() => {
+    if (fetcher.data) {
+      if (!fetcher.data.success && fetcher.data.error) {
+        // 登录失败，显示错误
+        console.error("❌ [Login] 登录失败:", fetcher.data.error);
+        setPasswordLoginError(fetcher.data.error);
+        toastService.error(fetcher.data.error);
+      }
+      // 登录成功的情况由 action 中的 redirect 处理，会自动跳转到 callback 页面
+    }
+  }, [fetcher.data]);
+
   useEffect(() => {
     // 检查OAuth配置是否完整（客户端不需要检查 clientSecret）
     if (!CLIENT_OAUTH_CONFIG.serverUrl || !CLIENT_OAUTH_CONFIG.clientId) {
@@ -279,9 +375,7 @@ export default function Login() {
                 </div>
               )}
               
-              <Form method="post" className="admin-login-form" onSubmit={handlePasswordLoginSubmit}>
-                <input type="hidden" name="intent" value="password_login" />
-                
+              <form className="admin-login-form" onSubmit={handlePasswordLoginSubmit}>
                 <div className="form-group">
                   <label htmlFor="username" className="form-label">用户名</label>
                   <input
@@ -292,10 +386,11 @@ export default function Login() {
                     onChange={(e) => setUsername(e.target.value)}
                     className="form-input"
                     placeholder="请输入用户名"
+                    disabled={isLoading}
                     required
                   />
                 </div>
-                
+
                 <div className="form-group">
                   <label htmlFor="password" className="form-label">密码</label>
                   <input
@@ -306,18 +401,19 @@ export default function Login() {
                     onChange={(e) => setPassword(e.target.value)}
                     className="form-input"
                     placeholder="请输入密码"
+                    disabled={isLoading}
                     required
                   />
                 </div>
-                
-                <button 
+
+                <button
                   type="submit"
                   className="admin-login-button"
-                  disabled={isLocked}
-                  style={isLocked ? { opacity: 0.5, cursor: 'not-allowed' } : {}}
+                  disabled={isLocked || isLoading}
+                  style={(isLocked || isLoading) ? { opacity: 0.5, cursor: 'not-allowed' } : {}}
                 >
-                  <i className={isLocked ? "ri-lock-line" : "ri-login-box-line"}></i>
-                  {isLocked ? "账户已锁定" : "登录"}
+                  <i className={isLocked ? "ri-lock-line" : isLoading ? "ri-loader-4-line" : "ri-login-box-line"}></i>
+                  {isLocked ? "账户已锁定" : isLoading ? "登录中..." : "登录"}
                 </button>
                 
                 {isLocked && (
@@ -334,7 +430,7 @@ export default function Login() {
                     <i className="ri-information-line"></i> 账户已被锁定，请联系管理员解锁
                   </div>
                 )}
-              </Form>
+              </form>
               
               <div className="back-to-oauth">
                 <button 
diff --git a/app/routes/reviews.tsx b/app/routes/reviews.tsx
index f176d8c..d8d39f4 100644
--- a/app/routes/reviews.tsx
+++ b/app/routes/reviews.tsx
@@ -541,7 +541,7 @@ export default function ReviewDetails() {
         if (result.success) {
           toastService.success('评查结果已确认，文档审核状态已更新');
           // 导航到文档列表页
-          navigate('/documents');
+          navigate('/documents/list');
         } else {
           console.error('确认评查结果失败:', result.error);
           toastService.error(`确认评查结果失败: ${result.error || '未知错误'}`);
@@ -622,7 +622,7 @@ export default function ReviewDetails() {
       if (loaderData.previousRoute === 'filesUpload') {
         items.unshift({ title: "文件上传", to: "/files/upload" });
       } else if (loaderData.previousRoute === 'documents') {
-        items.unshift({ title: "文档列表", to: "/documents" });
+        items.unshift({ title: "文档列表", to: "/documents/list" });
       } else if (loaderData.previousRoute === 'rulesFiles') {
         items.unshift({ title: "评查文件列表", to: "/rules-files" });
       }
diff --git a/app/routes/rules-files.tsx b/app/routes/rules-files.tsx
index b71bed8..5930db7 100644
--- a/app/routes/rules-files.tsx
+++ b/app/routes/rules-files.tsx
@@ -63,17 +63,17 @@ export async function loader({ request }: LoaderFunctionArgs) {
   // 获取用户会话信息
   const { getUserSession } = await import("~/api/login/auth.server");
   const { userInfo, frontendJWT } = await getUserSession(request);
-  
+
   // 获取分页参数
   const url = new URL(request.url);
   const currentPage = parseInt(url.searchParams.get("page") || "1", 10);
   const pageSize = parseInt(url.searchParams.get("pageSize") || "10", 10);
-  
+
   try {
-    // 获取文档类型列表
+    // 获取文档类型列表（服务端需要显式传递 token，客户端依赖 axios 拦截器）
     const typesResponse = await getDocumentTypes({pageSize:500}, frontendJWT);
     const documentTypes = typesResponse.data?.types || [];
-    
+
     // 返回初始空数据，客户端将根据 sessionStorage 中的 reviewType 加载实际数据
     return Response.json({
       files: [],
@@ -82,7 +82,6 @@ export async function loader({ request }: LoaderFunctionArgs) {
       currentPage,
       pageSize,
       userInfo, // 传递用户信息到客户端
-      frontendJWT,
       initialLoad: true
     });
   } catch (error) {
@@ -93,7 +92,7 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
 export default function RulesFiles() {
   const navigate = useNavigate();
-  const { files: initialFiles, documentTypes: allDocumentTypes, totalCount: initialTotal, currentPage, pageSize, userInfo, frontendJWT, result, message } = useLoaderData<typeof loader>();
+  const { files: initialFiles, documentTypes: allDocumentTypes, totalCount: initialTotal, currentPage, pageSize, userInfo, result, message } = useLoaderData<typeof loader>();
   const [searchParams, setSearchParams] = useSearchParams();
   const dateFrom = searchParams.get('dateFrom') || '';
   const dateTo = searchParams.get('dateTo') || '';
@@ -141,12 +140,28 @@ export default function RulesFiles() {
     }
   }, [result, message]);
 
+  // 辅助函数：从 localStorage 获取用户ID
+  const getUserId = useCallback((): string | undefined => {
+    if (typeof window === 'undefined') return undefined;
+
+    const userInfoStr = localStorage.getItem('user_info');
+    if (!userInfoStr) return undefined;
+
+    try {
+      const userInfoData = JSON.parse(userInfoStr);
+      return userInfoData.user_id?.toString();
+    } catch (error) {
+      console.error('解析 localStorage 用户信息失败:', error);
+      return undefined;
+    }
+  }, []);
+
   // 客户端数据请求
   const fetchData = useCallback(async (params: Record<string, string>) => {
     setIsLoading(true);
-    
+
     try {
-      // 构建搜索参数
+      // 构建搜索参数（token 由 axios 拦截器自动从 localStorage 获取）
       const searchParams: DocumentSearchParams = {
         fileType: params.fileType || undefined,
         reviewStatus: params.reviewStatus || undefined,
@@ -157,7 +172,7 @@ export default function RulesFiles() {
         page: parseInt(params.page || "1", 10),
         pageSize: parseInt(params.pageSize || "10", 10)
       };
-      
+
       // 根据 reviewType 添加类型过滤
       if (reviewType === 'contract') {
         searchParams.fileType = 'contract';
@@ -165,21 +180,24 @@ export default function RulesFiles() {
         // 在 API 层处理 type_id 为 2 或 3 的过滤
         searchParams.fileType = 'record';
       }
-      
+
       // 如果用户手动选择了文件类型，优先使用用户选择的
       if (params.fileType) {
         searchParams.fileType = params.fileType;
       }
 
-      // 从loader data中获取用户ID
-      const userId = userInfo?.user_id?.toString();
-      
-      // 获取文件列表
-      const filesResponse = await getReviewFiles({...searchParams, token: frontendJWT}, null, userId);
+      // 从 localStorage 获取用户ID（与 token 管理保持一致）
+      const userId = getUserId();
+      if (!userId) {
+        throw new Error('用户身份验证失败，无法获取评查文件列表');
+      }
+
+      // 获取文件列表（token 由 axios 拦截器自动添加）
+      const filesResponse = await getReviewFiles(searchParams, null, userId);
       if (filesResponse.error) {
         throw new Error(filesResponse.error);
       }
-      
+
       setFiles(filesResponse.data?.files || []);
       setTotalCount(filesResponse.data?.total || 0);
     } catch (error) {
@@ -188,7 +206,7 @@ export default function RulesFiles() {
     } finally {
       setIsLoading(false);
     }
-  }, [reviewType]);
+  }, [reviewType, getUserId]); // 使用 getUserId 辅助函数
 
   // 在组件挂载时从 sessionStorage 获取 reviewType 并加载数据
   useEffect(() => {
@@ -234,17 +252,19 @@ export default function RulesFiles() {
           if (currentParams.fileType) {
             apiSearchParams.fileType = currentParams.fileType;
           }
-          
+
           // 设置加载状态
           setIsLoading(true);
-          
-          // 从loader data中获取用户ID
-          const userId = userInfo?.user_id?.toString();
 
-          // 添加 token 参数到 apiSearchParams
-          apiSearchParams.token = frontendJWT;
+          // 从 localStorage 获取用户ID
+          const userId = getUserId();
+          if (!userId) {
+            toastService.error('用户身份验证失败，无法获取评查文件列表');
+            setIsLoading(false);
+            return;
+          }
 
-          // 获取文件列表
+          // 获取文件列表（token 由 axios 拦截器自动添加）
           getReviewFiles(apiSearchParams, null, userId)
             .then(filesResponse => {
               if (filesResponse.error) {
@@ -331,14 +351,15 @@ export default function RulesFiles() {
     // 检查audit_status是否为0，如果是则更新为2
     if (auditStatus === 0 || auditStatus === null) {
       try {
-        // 从loader data中获取用户ID
-        const userId = userInfo?.user_id?.toString();
+        // 从 localStorage 获取用户ID
+        const userId = getUserId();
         if (!userId) {
           toastService.error('用户身份验证失败');
           return;
         }
-        
-        const response = await updateDocumentAuditStatus(fileId, 2, userId, frontendJWT);
+
+        // token 由 axios 拦截器自动添加
+        const response = await updateDocumentAuditStatus(fileId, 2, userId);
         if (response.error) {
           throw new Error(response.error);
         }
@@ -348,7 +369,7 @@ export default function RulesFiles() {
         return;
       }
     }
-    
+
     // 导航到评查详情页
     // 在离开当前页前保存当前查询参数，返回时可恢复
     if (typeof window !== 'undefined') {
@@ -520,8 +541,7 @@ export default function RulesFiles() {
         attachmentFiles,
         attachmentMergeMode,
         true,
-        attachmentRemark || undefined,
-        frontendJWT as string | undefined
+        attachmentRemark || undefined
       );
       if (result.error) {
         throw new Error(result.error);
diff --git a/app/routes/rules._index.tsx b/app/routes/rules.list.tsx
similarity index 91%
rename from app/routes/rules._index.tsx
rename to app/routes/rules.list.tsx
index b37e65d..4ecd7f1 100644
--- a/app/routes/rules._index.tsx
+++ b/app/routes/rules.list.tsx
@@ -89,42 +89,47 @@ function mapApiRuleToModel(apiRule: ApiRule): Rule {
 
 export async function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url);
-  
+
   // 从 URL 参数中提取查询条件
   const params = {
     page: parseInt(url.searchParams.get("page") || "1", 10),
     pageSize: parseInt(url.searchParams.get("pageSize") || "10", 10)
   };
-  
+
   try {
-    // 获取用户会话信息
-    const { getUserSession } = await import("~/api/login/auth.server");
-    const { frontendJWT } = await getUserSession(request);
-    
-    // 获取评查点类型列表，供前端筛选使用
-    const typeResponse = await getRuleTypes(undefined, frontendJWT);
-    
-    if (typeResponse.error) {
-      console.error('获取评查点类型失败:', typeResponse.error);
-    }
-    
-    const ruleTypes = typeResponse.error ? [] : typeResponse.data;
-    
-    // 返回初始空数据，客户端将根据 sessionStorage 中的 reviewType 加载实际数据
-    return Response.json({
-      rules: [],
-      totalCount: 0,
-      currentPage: params.page,
-      pageSize: params.pageSize,
-      ruleTypes,
-      initialLoad: true,
-      frontendJWT
-    }, {
-      headers: {
-        "Cache-Control": "max-age=60, s-maxage=180"
+    // 🔑 使用 handleServerAuth 包装，自动处理 token 过期
+    const { handleServerAuth } = await import("~/utils/server-auth-handler");
+
+    return handleServerAuth(async () => {
+      // 获取用户会话信息
+      const { getUserSession } = await import("~/api/login/auth.server");
+      const { frontendJWT } = await getUserSession(request);
+
+      // 获取评查点类型列表，供前端筛选使用
+      const typeResponse = await getRuleTypes(undefined, frontendJWT);
+
+      if (typeResponse.error) {
+        console.error('获取评查点类型失败:', typeResponse.error);
       }
-    });
-    
+
+      const ruleTypes = typeResponse.error ? [] : typeResponse.data;
+
+      // 返回初始空数据，客户端将根据 sessionStorage 中的 reviewType 加载实际数据
+      return Response.json({
+        rules: [],
+        totalCount: 0,
+        currentPage: params.page,
+        pageSize: params.pageSize,
+        ruleTypes,
+        initialLoad: true,
+        frontendJWT
+      }, {
+        headers: {
+          "Cache-Control": "max-age=60, s-maxage=180"
+        }
+      });
+    }, url.pathname);
+
   } catch (error) {
     console.error('加载评查点列表失败:', error);
     return Response.json({
@@ -135,31 +140,38 @@ export async function loader({ request }: LoaderFunctionArgs) {
 }
 
 export async function action({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
   const formData = await request.formData();
   const _action = formData.get('_action');
   const ruleId = formData.get('ruleId');
-  
+
   if (!ruleId) {
     return Response.json({ result: false, message: "缺少评查点ID" }, { status: 400 });
   }
 
   try {
-    // 获取用户会话信息
-    const { getUserSession } = await import("~/api/login/auth.server");
-    const { frontendJWT } = await getUserSession(request);
-    
-    if (_action === 'delete') {
-      // 调用API删除评查点
-      // console.log(`删除评查点 ${ruleId}`);
-      
-      const deleteResponse = await deleteRule(ruleId as string, frontendJWT);
-      
-      if (deleteResponse.error) {
-        return Response.json({ result: false, message: deleteResponse.error }, { status: deleteResponse.status || 500 });
+    // 🔑 使用 handleServerAuth 包装，自动处理 token 过期
+    const { handleServerAuth } = await import("~/utils/server-auth-handler");
+
+    return handleServerAuth(async () => {
+      // 获取用户会话信息
+      const { getUserSession } = await import("~/api/login/auth.server");
+      const { frontendJWT } = await getUserSession(request);
+
+      if (_action === 'delete') {
+        // 调用API删除评查点
+        const deleteResponse = await deleteRule(ruleId as string, frontendJWT);
+
+        if (deleteResponse.error) {
+          return Response.json({ result: false, message: deleteResponse.error }, { status: deleteResponse.status || 500 });
+        }
+
+        return Response.json({ result: true, message: "评查点删除成功" }, { status: 200 });
       }
 
-      return Response.json({ result: true, message: "评查点删除成功" }, { status: 200 });
-    }
+      return Response.json({ result: false, message: "未知操作" }, { status: 400 });
+    }, url.pathname);
+
   } catch (error) {
     console.error('操作评查点失败:', error);
     return Response.json({ result: false, message: error instanceof Error ? error.message : "操作失败" }, { status: 500 });
@@ -232,6 +244,11 @@ export default function RulesIndex() {
   // 检查用户是否为开发者角色
   const userRole = rootData?.userRole || 'common';
   const isDeveloper = userRole === 'admin';
+
+  // 调试日志
+  // console.log("🔑 [Rules List] rootData:", rootData);
+  // console.log("🔑 [Rules List] 用户角色:", userRole);
+  // console.log("🔑 [Rules List] 是否为管理员:", isDeveloper);
   
   // 在组件渲染时初始化状态
   // useEffect(() => {  
diff --git a/app/routes/rules.new1.tsx b/app/routes/rules.new1.tsx
deleted file mode 100644
index 9dd4122..0000000
--- a/app/routes/rules.new1.tsx
+++ /dev/null
@@ -1,572 +0,0 @@
-/**
- * 文档预览与内容抽取模块
- * 
- * 依赖包说明:
- * 1. react-pdf - PDF文档预览
- *    安装命令: npm install react-pdf
- *    或: yarn add react-pdf
- * 
- * 2. mammoth - Word文档转HTML预览
- *    安装命令: npm install mammoth
- *    或: yarn add mammoth
- * 
- * 3. @remix-run/react, @remix-run/node - Remix框架组件
- *    安装命令: npm install @remix-run/react @remix-run/node
- *    或: yarn add @remix-run/react @remix-run/node
- * 
- * 注意事项:
- * - react-pdf需要pdfjs-dist作为依赖，安装react-pdf时会自动安装
- * - 需要引入PDF.js worker文件，本代码通过CDN方式引入
- * - 如需本地加载PDF.js worker文件，请安装pdfjs-dist并修改worker配置
- */
-
-import { useState, useEffect, useRef } from "react";
-import { useLoaderData } from "@remix-run/react";
-import { Document, Page, pdfjs } from "react-pdf";
-import type { LoaderFunctionArgs } from "@remix-run/node";
-import mammoth from "mammoth";
-
-/**
- * 设置 pdfjs 工作线程
- * 使用 CDN 上的 worker.js 文件处理 PDF 解析
- */
-pdfjs.GlobalWorkerOptions.workerSrc = `//cdnjs.cloudflare.com/ajax/libs/pdf.js/${pdfjs.version}/pdf.worker.js`;
-
-/**
- * 模拟后端返回的文档抽取内容数据
- * 实际应用中应从API获取
- */
-const mockExtractedContent = [
-  { id: 1, text: "合同条款", page: 2, position: { start: 50, end: 60 } },
-  { id: 2, text: "签署日期", page: 5, position: { start: 120, end: 130 } },
-  { id: 3, text: "责任划分", page: 3, position: { start: 80, end: 90 } },
-];
-
-/**
- * 文档抽取内容接口定义
- */
-interface ExtractedContent {
-  id: number;           // 内容唯一标识
-  text: string;         // 抽取的文本内容
-  page: number;         // 所在页码
-  position: {           // 在页面中的位置信息
-    start: number;
-    end: number;
-  };
-}
-
-/**
- * Loader 函数返回数据接口定义
- */
-interface LoaderData {
-  fileUrl: string;                       // 当前文档URL
-  initialPage: number;                   // 初始页码
-  extractedContent: ExtractedContent[];  // 抽取内容数组
-  fileType: "pdf" | "docx";              // 文档类型
-  urls: Record<string, string>;          // 可用文档URL列表
-}
-
-/**
- * PDF文档加载成功回调接口
- */
-interface DocumentLoadSuccess {
-  numPages: number;  // 文档总页数
-}
-
-/**
- * 根据URL判断文件类型
- * @param url 文档URL
- * @returns 文档类型："pdf" 或 "docx"
- */
-function getFileTypeFromUrl(url: string): "pdf" | "docx" {
-  const lowerCaseUrl = url.toLowerCase();
-  if (lowerCaseUrl.endsWith(".pdf")) {
-    return "pdf";
-  } else if (lowerCaseUrl.endsWith(".docx") || lowerCaseUrl.endsWith(".doc")) {
-    return "docx";
-  }
-  // 默认当作PDF处理
-  return "pdf";
-}
-
-/**
- * Remix Loader 函数 - 请求处理和数据加载
- */
-export const loader = async ({ request }: LoaderFunctionArgs) => {
-  // 从URL获取查询参数
-  const url = new URL(request.url);
-  const page = url.searchParams.get("page") || 1;
-  
-  // 示例文档URLs集合
-  const urls = {
-    // 1. 原始文档URL - 可能有CORS限制
-    original: "https://dev-xc-enroll.oss-cn-guangzhou.aliyuncs.com/uploads/7840-230620112939.docx",
-    // 2. 公开示例文档 - 仍可能有CORS限制
-    public: "https://dev-xc-enroll.oss-cn-guangzhou.aliyuncs.com/uploads/7840-230620112939.docx",
-    // 3. 通过CORS代理 (示例)
-    proxy: "https://dev-xc-enroll.oss-cn-guangzhou.aliyuncs.com/uploads/7840-230620112939.docx",
-    // 4. 本地服务器上的文档 (假设已经部署)
-    local: "/uploads/sample.docx",
-    // 5. PDF示例
-    pdf: "http://nas.7bm.co:9000/docauditai/documents/%E5%90%88%E5%90%8C%E6%96%87%E6%A1%A3/2025/04%E6%9C%8816%E6%97%A5/%E7%AC%AC16%E5%8F%B7--%E9%94%80%E5%94%AE%E6%97%A0%E6%A0%87%E5%BF%97%E5%A4%96%E5%9B%BD%E5%8D%B7%E7%83%9F_10%E6%97%B626%E5%88%8632%E7%A7%92/%E7%AC%AC16%E5%8F%B7--%E9%94%80%E5%94%AE%E6%97%A0%E6%A0%87%E5%BF%97%E5%A4%96%E5%9B%BD%E5%8D%B7%E7%83%9F.pdf"
-  };
-  
-  // 使用默认文档URL
-  const fileUrl = urls.pdf;
-  
-  // 判断文件类型
-  const fileType = getFileTypeFromUrl(fileUrl);
-  
-  // 返回加载的数据
-  return { 
-    fileUrl, 
-    initialPage: Number(page), 
-    extractedContent: mockExtractedContent,
-    fileType,
-    urls
-  };
-};
-
-/**
- * 文档预览组件
- */
-export default function Documents() {
-  // 从loader获取数据
-  const { fileUrl, extractedContent, fileType, urls } = useLoaderData<LoaderData>();
-  
-  // 状态管理
-  const [numPages, setNumPages] = useState<number | null>(null);                // PDF总页数
-  const [scrollToPage, setScrollToPage] = useState<number | null>(null);        // 滚动目标页码
-  const [docxLoading, setDocxLoading] = useState(false);                        // Word文档加载状态
-  const [loadError, setLoadError] = useState<string | null>(null);              // 加载错误信息
-  const [debugInfo, setDebugInfo] = useState<string[]>([]);                     // 调试信息
-  const [docxHtml, setDocxHtml] = useState<string>("");                         // 转换后的HTML内容
-  const [currentUrl, setCurrentUrl] = useState<string>(fileUrl);                // 当前文档URL
-  
-  // 引用
-  const docxContainerRef = useRef<HTMLDivElement>(null);                        // Word文档容器引用
-
-  /**
-   * 处理抽取内容点击事件 - 仅对PDF文档生效
-   * @param item 被点击的抽取内容项
-   */
-  const handleContentClick = (item: ExtractedContent) => {
-    // 仅对PDF文档执行交互操作
-    if (fileType === "pdf") {
-      setScrollToPage(item.page);
-      // 对于PDF，滚动到指定页面
-      const pageElement = document.getElementById(`page-${item.page}`);
-      if (pageElement) {
-        pageElement.scrollIntoView({ behavior: 'smooth' });
-      }
-    }
-    // DOCX文档不执行任何交互操作
-  };
-
-  /**
-   * PDF文档加载成功回调函数
-   * @param param0 包含numPages的对象
-   */
-  function onDocumentLoadSuccess({ numPages }: DocumentLoadSuccess) {
-    setNumPages(numPages);
-    // console.log("PDF加载成功，页数:", numPages);
-  }
-
-  /**
-   * 添加调试信息
-   * @param info 调试信息文本
-   */
-  const addDebugInfo = (info: string) => {
-    // console.log(info);
-    setDebugInfo(prev => [...prev, `${new Date().toISOString().split('T')[1].split('.')[0]}: ${info}`]);
-  };
-
-  /**
-   * 切换文档URL
-   * @param urlKey URL键名
-   */
-  const switchDocumentUrl = (urlKey: keyof typeof urls) => {
-    setCurrentUrl(urls[urlKey]);
-    setDebugInfo([]);
-    setLoadError(null);
-    setDocxLoading(false);
-    addDebugInfo(`切换到新的文档URL: ${urls[urlKey]}`);
-  };
-
-  /**
-   * Word文档处理逻辑
-   */
-  useEffect(() => {
-    if (fileType === "docx" && docxContainerRef.current) {
-      setDocxLoading(true);
-      setDebugInfo([]); // 清空调试信息
-      addDebugInfo(`准备加载Word文档: ${currentUrl}`);
-      
-      const loadDocx = async () => {
-        try {
-          // 1. 获取文档文件
-          addDebugInfo(`开始获取文件...`);
-          let response;
-          try {
-            response = await fetch(currentUrl, {
-              mode: 'cors',
-              credentials: 'omit',
-              headers: {
-                'Access-Control-Allow-Origin': '*'
-              }
-            });
-            addDebugInfo(`fetch请求状态: ${response.status} ${response.statusText}`);
-          } catch (fetchError) {
-            addDebugInfo(`fetch请求失败: ${fetchError instanceof Error ? fetchError.message : String(fetchError)}`);
-            throw new Error(`网络请求失败: ${fetchError instanceof Error ? fetchError.message : String(fetchError)}`);
-          }
-          
-          // 检查响应状态
-          if (!response.ok) {
-            throw new Error(`文档无法访问，状态码: ${response.status}`);
-          }
-          addDebugInfo(`文档下载成功，状态码: ${response.status}`);
-          
-          // 2. 将响应转换为ArrayBuffer
-          addDebugInfo(`开始读取响应内容为ArrayBuffer...`);
-          let buffer;
-          try {
-            buffer = await response.arrayBuffer();
-            addDebugInfo(`获取到文档数据，大小: ${buffer.byteLength} 字节`);
-          } catch (bufferError) {
-            addDebugInfo(`读取为ArrayBuffer失败: ${bufferError instanceof Error ? bufferError.message : String(bufferError)}`);
-            throw new Error(`转换文档内容失败: ${bufferError instanceof Error ? bufferError.message : String(bufferError)}`);
-          }
-          
-          // 3. 使用mammoth.js将Word转换为HTML
-          addDebugInfo("使用mammoth开始转换文档为HTML...");
-          try {
-            // 自定义样式映射
-            const styleMap = `
-              p[style-name='Heading 1'] => h1:fresh
-              p[style-name='Heading 2'] => h2:fresh
-              p[style-name='Title'] => h1.title:fresh
-              p[style-name='Subtitle'] => h2.subtitle:fresh
-              table => table.docx-table
-            `;
-            
-            // 转换选项
-            const options = {
-              arrayBuffer: buffer,
-              styleMap: styleMap,
-              includeDefaultStyleMap: true
-            };
-            
-            // 执行转换
-            const result = await mammoth.convertToHtml(options);
-            
-            // 检查转换警告
-            if (result.messages.length > 0) {
-              result.messages.forEach(message => {
-                addDebugInfo(`转换警告: [${message.type}] ${message.message}`);
-              });
-            }
-            
-            addDebugInfo("文档转换成功，获取到HTML内容");
-            
-            // 4. 为生成的HTML添加包装容器和样式
-            const enhancedHtml = `
-              <div class="document-container">
-                ${result.value}
-                <div class="format-note">
-                  <p>注意：部分复杂格式(如页眉页脚、复杂表格样式)可能无法完全显示。</p>
-                </div>
-              </div>
-            `;
-            
-            // 更新状态
-            setDocxHtml(enhancedHtml);
-            setDocxLoading(false);
-          } catch (mammothError) {
-            addDebugInfo(`Mammoth转换失败: ${mammothError instanceof Error ? mammothError.message : String(mammothError)}`);
-            throw new Error(`Word转HTML失败: ${mammothError instanceof Error ? mammothError.message : String(mammothError)}`);
-          }
-        } catch (error: unknown) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          addDebugInfo(`文档处理错误: ${errorMessage}`);
-          setLoadError(`加载Word文档失败: ${errorMessage}`);
-          setDocxLoading(false);
-        }
-      };
-      
-      loadDocx();
-    }
-  }, [currentUrl, fileType]);
-
-  /**
-   * 页面滚动逻辑
-   */
-  useEffect(() => {
-    if (scrollToPage && fileType === "pdf") {
-      const pageElement = document.getElementById(`page-${scrollToPage}`);
-      if (pageElement) {
-        pageElement.scrollIntoView({ behavior: 'smooth' });
-      }
-      setScrollToPage(null);
-    }
-  }, [scrollToPage, fileType]);
-
-  /**
-   * 生成所有PDF页面的渲染数组
-   * @returns 页面组件数组
-   */
-  const renderAllPages = () => {
-    if (!numPages) return null;
-    
-    const pages = [];
-    for (let i = 1; i <= numPages; i++) {
-      pages.push(
-        <div key={i} id={`page-${i}`} className="mb-6">
-          <div className="text-center text-gray-500 text-sm mb-2">第 {i} 页</div>
-          <Page
-            pageNumber={i}
-            renderTextLayer={false}
-            renderAnnotationLayer={false}
-            className="border border-gray-300 shadow-md"
-          />
-        </div>
-      );
-    }
-    return pages;
-  };
-
-  return (
-    <div className="flex h-screen bg-gray-50">
-      {/* 文档展示区域 */}
-      <div className="flex-1 mr-6 p-4">
-        <div className="bg-white p-4 rounded-lg shadow-md h-full flex flex-col">
-          <h1 className="text-2xl font-bold mb-4">文档预览 ({fileType.toUpperCase()})</h1>
-          
-          {/* 文档内容显示区域 */}
-          <div className="w-full flex-1 overflow-auto bg-gray-100 rounded-lg p-4">
-            {loadError ? (
-              <div className="text-red-500 flex flex-col items-center justify-center h-full">
-                <p className="mb-4">加载错误:</p>
-                <p>{loadError}</p>
-                <div className="mt-6 p-4 bg-gray-800 text-green-400 rounded text-xs max-w-xl overflow-auto max-h-96">
-                  <p className="font-bold mb-2">调试信息:</p>
-                  {debugInfo.map((info, index) => (
-                    <div key={index} className="mb-1">{info}</div>
-                  ))}
-                </div>
-                <div className="mt-4">
-                  <p className="text-black mb-2">尝试其他方式:</p>
-                  <div className="flex flex-wrap gap-2">
-                    <button onClick={() => switchDocumentUrl('public')} className="px-3 py-1 bg-green-500 text-white rounded">
-                      使用公共示例
-                    </button>
-                    <button onClick={() => switchDocumentUrl('proxy')} className="px-3 py-1 bg-blue-500 text-white rounded">
-                      使用CORS代理
-                    </button>
-                    <button onClick={() => switchDocumentUrl('pdf')} className="px-3 py-1 bg-yellow-500 text-white rounded">
-                      切换到PDF
-                    </button>
-                    <a href={currentUrl} className="px-3 py-1 bg-gray-500 text-white rounded" download target="_blank" rel="noreferrer">
-                      下载文档
-                    </a>
-                  </div>
-                </div>
-              </div>
-            ) : fileType === "pdf" ? (
-              /* PDF 文档渲染 */
-              <Document
-                file={currentUrl}
-                onLoadSuccess={onDocumentLoadSuccess}
-                onLoadError={(error) => {
-                  console.error("PDF加载错误:", error);
-                  setLoadError("PDF文档加载失败：" + (error.message || "未知错误"));
-                }}
-                className="flex flex-col items-center"
-                error={<div className="text-red-500">PDF文档加载失败，请检查链接或网络连接。</div>}
-                noData={<div>无数据</div>}
-                loading={<div className="text-center py-10">PDF加载中...</div>}
-              >
-                {renderAllPages()}
-              </Document>
-            ) : (
-              /* Word 文档渲染 */
-              <>
-                {docxLoading ? (
-                  /* 加载状态显示 */
-                  <div className="flex flex-col items-center justify-center h-full">
-                    <div className="mb-6">
-                      <div className="animate-spin rounded-full h-12 w-12 border-t-2 border-b-2 border-blue-500"></div>
-                    </div>
-                    <p className="mb-4 text-lg">Word文档加载中...</p>
-                    {debugInfo.length > 0 && (
-                      <div className="mt-4 p-4 bg-gray-800 text-green-400 rounded text-xs max-w-xl overflow-auto max-h-72">
-                        <p className="font-bold mb-2">加载过程:</p>
-                        {debugInfo.map((info, index) => (
-                          <div key={index} className="mb-1">{info}</div>
-                        ))}
-                      </div>
-                    )}
-                  </div>
-                ) : (
-                  /* 本地渲染的Word文档 */
-                  <div 
-                    ref={docxContainerRef} 
-                    className="w-full h-full"
-                    style={{
-                      height: '100%',
-                      overflowY: 'auto',
-                      padding: '20px',
-                      backgroundColor: 'white'
-                    }}
-                    dangerouslySetInnerHTML={{ __html: docxHtml }}
-                  />
-                )}
-              </>
-            )}
-          </div>
-        </div>
-      </div>
-
-      {/* 抽取内容区域 - 始终显示，但DOCX模式下不交互 */}
-      <div className="w-80 bg-white p-4 rounded-lg shadow-md mr-4 my-4 overflow-auto">
-        <h2 className="text-xl font-semibold mb-4">抽取内容</h2>
-        <ul className="space-y-3">
-          {extractedContent.map((item) => (
-            <button
-              key={item.id}
-              onClick={() => handleContentClick(item)}
-              className={`w-full text-left p-3 ${fileType === "pdf" ? "bg-gray-50 hover:bg-gray-100 cursor-pointer" : "bg-gray-100"} rounded-lg transition`}
-              disabled={fileType === "docx"}
-              aria-label={`查看内容: ${item.text}`}
-            >
-              <p className="text-sm font-medium">{item.text}</p>
-              <p className="text-xs text-gray-500">页面: {item.page}</p>
-            </button>
-          ))}
-        </ul>
-      </div>
-      
-      {/* 添加自定义样式 */}
-      <style dangerouslySetInnerHTML={{
-        __html: `
-          /* 高亮显示样式 */
-          .docx-highlight {
-            background-color: #ffff00;
-            outline: 2px solid orange;
-            position: relative;
-          }
-          
-          /* 找到的内容高亮样式 */
-          .docx-content-found {
-            background-color: rgba(255, 230, 0, 0.3);
-            outline: 1px solid orange;
-          }
-          
-          /* Mammoth.js生成的内容样式 */
-          .document-container {
-            font-family: "Microsoft YaHei", Arial, sans-serif;
-            line-height: 1.5;
-            color: #333;
-            max-width: 800px;
-            margin: 0 auto;
-          }
-          
-          .document-container .format-note {
-            margin-top: 30px;
-            padding: 10px;
-            background-color: #f5f5f5;
-            border-left: 3px solid #ccc;
-            font-size: 12px;
-            color: #666;
-          }
-          
-          .document-container h1 {
-            font-size: 24px;
-            margin-top: 24px;
-            margin-bottom: 16px;
-            font-weight: bold;
-            color: #222;
-          }
-          
-          .document-container h1.title {
-            font-size: 28px;
-            text-align: center;
-            margin-bottom: 24px;
-          }
-          
-          .document-container h2 {
-            font-size: 20px;
-            margin-top: 20px;
-            margin-bottom: 14px;
-            font-weight: bold;
-            color: #333;
-          }
-          
-          .document-container h2.subtitle {
-            font-size: 18px;
-            text-align: center;
-            margin-bottom: 20px;
-            color: #555;
-          }
-          
-          .document-container p {
-            margin-bottom: 16px;
-            text-align: justify;
-            overflow-wrap: break-word;
-          }
-          
-          .document-container table {
-            border-collapse: collapse;
-            width: 100%;
-            margin-bottom: 16px;
-          }
-          
-          .document-container table.docx-table {
-            border: 1px solid #ddd;
-            margin: 16px 0;
-          }
-          
-          .document-container table.docx-table th, 
-          .document-container table.docx-table td {
-            border: 1px solid #ddd;
-            padding: 8px;
-            text-align: left;
-          }
-          
-          .document-container table.docx-table th {
-            background-color: #f2f2f2;
-            font-weight: bold;
-          }
-          
-          .document-container ul, .document-container ol {
-            margin-left: 20px;
-            margin-bottom: 16px;
-          }
-          
-          .document-container li {
-            margin-bottom: 5px;
-          }
-          
-          .document-container img {
-            max-width: 100%;
-            height: auto;
-            margin: 10px 0;
-          }
-          
-          .document-container span.underline {
-            text-decoration: underline;
-          }
-          
-          .document-container span.strikethrough {
-            text-decoration: line-through;
-          }
-          
-          /* 段落缩进 */
-          .document-container p:not(.no-indent) {
-            text-indent: 2em;
-          }
-        `
-      }} />
-    </div>
-  );
-}
\ No newline at end of file
diff --git a/app/styles/components/document-version.css b/app/styles/components/document-version.css
new file mode 100644
index 0000000..4188c87
--- /dev/null
+++ b/app/styles/components/document-version.css
@@ -0,0 +1,202 @@
+/* ============================================
+ * 文档版本管理样式
+ * ============================================ */
+
+/* 历史版本行样式 */
+.history-row {
+  background-color: #fafafa !important;
+  border-left: 3px solid var(--color-primary, #00684a);
+  border-bottom: 1px solid #e8e8e8;
+}
+
+.history-row:hover {
+  background-color: #f0f0f0 !important;
+}
+
+/* 历史版本行的第一个单元格添加左侧缩进 */
+/* .history-row > td:first-child {
+  padding-left: 50px !important;
+} */
+
+/* 展开/折叠图标 */
+.expand-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  cursor: pointer;
+  color: #8c8c8c;
+  font-size: 18px;
+  transition: transform 0.2s ease, color 0.2s ease;
+  user-select: none;
+}
+
+.expand-icon:hover {
+  color: var(--color-primary, #00684a);
+}
+
+.expand-icon.expanded {
+  transform: rotate(90deg);
+}
+
+
+/* 版本徽章 */
+.version-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  background-color: #f0f0f0;
+  color: #8c8c8c;
+  border-radius: 4px;
+  font-size: 12px;
+  margin-left: 8px;
+}
+
+.version-badge i {
+  font-size: 14px;
+}
+
+/* 版本号标签 */
+.version-number {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 8px;
+  background-color: #e6f7ff;
+  color: #1890ff;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+/* 问题数量差异显示 */
+.issues-count-wrapper {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.issues-number {
+  font-weight: 600;
+  font-size: 14px;
+  color: #262626;
+}
+
+.issues-diff {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+/* 问题数量增加（红色） */
+.issues-diff.increase {
+  color: #f5222d;
+  background-color: #fff1f0;
+}
+
+.issues-diff.increase i {
+  color: #f5222d;
+}
+
+/* 问题数量减少（绿色） */
+.issues-diff.decrease {
+  color: #52c41a;
+  background-color: #f6ffed;
+}
+
+.issues-diff.decrease i {
+  color: #52c41a;
+}
+
+/* 问题数量相同（灰色） */
+.issues-diff.same {
+  color: #8c8c8c;
+  background-color: #f5f5f5;
+}
+
+.issues-diff.same i {
+  color: #8c8c8c;
+}
+
+/* 文档名称文本 */
+.doc-name-text {
+  word-break: break-word;
+  line-height: 1.5;
+}
+
+/* 历史版本标签 */
+.history-version-label {
+  font-weight: 500;
+  color: #595959;
+}
+
+/* 响应式设计 */
+@media (max-width: 768px) {
+  .history-row > td:first-child {
+    padding-left: 30px !important;
+  }
+
+  .expand-icon {
+    font-size: 16px;
+  }
+
+  .version-badge {
+    font-size: 11px;
+    padding: 1px 6px;
+  }
+
+  .issues-diff {
+    font-size: 11px;
+    padding: 1px 6px;
+  }
+}
+
+/* 加载状态 */
+.version-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 12px;
+  color: #8c8c8c;
+  font-size: 14px;
+}
+
+.version-loading i {
+  margin-right: 8px;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* 空状态 */
+.version-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 12px;
+  color: #8c8c8c;
+  font-size: 14px;
+}
+
+/* 确保 RemixIcon 样式不被覆盖 */
+.expand-icon i,
+.history-icon i,
+.version-badge i,
+.issues-diff i {
+  font-family: 'remixicon' !important;
+  font-style: normal;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
diff --git a/app/styles/main.css b/app/styles/main.css
index d95fe95..239327f 100644
--- a/app/styles/main.css
+++ b/app/styles/main.css
@@ -27,6 +27,7 @@
 @import './components/message-modal.css';
 @import './components/toast.css';
 @import './components/TooltipStyles.css';
+@import './components/document-version.css';
 
 /* @import './components/modal.css'; */
 
diff --git a/app/styles/pages/login.css b/app/styles/pages/login.css
index 6c6d81f..22dc4ad 100644
--- a/app/styles/pages/login.css
+++ b/app/styles/pages/login.css
@@ -10,6 +10,20 @@
   background-repeat: no-repeat;
 }
 
+/* 加载图标旋转动画 */
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.ri-loader-4-line {
+  animation: spin 1s linear infinite;
+}
+
 .login-container {
   width: 100%;
   max-width: 480px;
diff --git a/app/utils/auth-storage.ts b/app/utils/auth-storage.ts
new file mode 100644
index 0000000..f63ae3d
--- /dev/null
+++ b/app/utils/auth-storage.ts
@@ -0,0 +1,105 @@
+/**
+ * 认证信息存储工具
+ * 用于在客户端（浏览器）存储和管理 JWT token 和用户信息
+ */
+
+/**
+ * 存储的用户信息接口
+ */
+export interface StoredUserInfo {
+  user_id: string;
+  username: string;
+  nick_name: string;
+  email?: string;
+  phone_number?: string;
+  ou_id: string;
+  ou_name: string;
+  is_leader: boolean;
+  user_role: string;
+  sub: string;
+}
+
+/**
+ * 存储 JWT token 到 localStorage
+ */
+export function storeAccessToken(token: string): void {
+  if (typeof window === 'undefined') {
+    console.warn('⚠️ storeAccessToken 只能在浏览器环境中使用');
+    return;
+  }
+  localStorage.setItem('access_token', token);
+  console.log('✅ Token 已存储到 localStorage');
+}
+
+/**
+ * 获取存储的 JWT token
+ */
+export function getAccessToken(): string | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  return localStorage.getItem('access_token');
+}
+
+/**
+ * 存储用户信息到 localStorage
+ */
+export function storeUserInfo(userInfo: StoredUserInfo): void {
+  if (typeof window === 'undefined') {
+    console.warn('⚠️ storeUserInfo 只能在浏览器环境中使用');
+    return;
+  }
+  localStorage.setItem('user_info', JSON.stringify(userInfo));
+  console.log('✅ 用户信息已存储到 localStorage');
+}
+
+/**
+ * 获取存储的用户信息
+ */
+export function getUserInfo(): StoredUserInfo | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  const userInfoStr = localStorage.getItem('user_info');
+  if (!userInfoStr) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(userInfoStr) as StoredUserInfo;
+  } catch (error) {
+    console.error('❌ 解析用户信息失败:', error);
+    return null;
+  }
+}
+
+/**
+ * 清除所有认证信息
+ */
+export function clearAuth(): void {
+  if (typeof window === 'undefined') {
+    console.warn('⚠️ clearAuth 只能在浏览器环境中使用');
+    return;
+  }
+
+  localStorage.removeItem('access_token');
+  localStorage.removeItem('user_info');
+  console.log('✅ 认证信息已清除');
+}
+
+/**
+ * 检查是否已登录（有有效的 token）
+ */
+export function isAuthenticated(): boolean {
+  const token = getAccessToken();
+  return !!token;
+}
+
+/**
+ * 存储完整的登录响应数据
+ */
+export function storeLoginData(accessToken: string, userInfo: StoredUserInfo): void {
+  storeAccessToken(accessToken);
+  storeUserInfo(userInfo);
+}
diff --git a/app/utils/server-auth-handler.ts b/app/utils/server-auth-handler.ts
new file mode 100644
index 0000000..c4e8308
--- /dev/null
+++ b/app/utils/server-auth-handler.ts
@@ -0,0 +1,72 @@
+/**
+ * 服务端认证错误处理工具
+ *
+ * 用于在 Remix loader/action 中统一处理 AuthenticationError（token 过期）
+ */
+
+import { redirect } from "@remix-run/node";
+
+/**
+ * 包装服务端异步函数，自动处理 AuthenticationError
+ *
+ * @param fn - 需要执行的异步函数
+ * @param pathname - 当前路径（用于保存重定向目标）
+ * @returns 函数执行结果，或在 token 过期时重定向到登录页
+ *
+ * @example
+ * // 在 loader 中使用
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const url = new URL(request.url);
+ *
+ *   return handleServerAuth(async () => {
+ *     const { getUserSession } = await import("~/api/login/auth.server");
+ *     const { frontendJWT } = await getUserSession(request);
+ *
+ *     // 调用需要认证的 API
+ *     const response = await getDocumentTypes({}, frontendJWT);
+ *
+ *     return Response.json({ data: response.data });
+ *   }, url.pathname);
+ * }
+ */
+export async function handleServerAuth<T>(
+  fn: () => Promise<T>,
+  pathname: string
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    // 检查是否是 AuthenticationError（token 过期）
+    if (error instanceof Error && error.name === 'AuthenticationError') {
+      console.warn(`⚠️ [Server Auth Handler] Token 过期，重定向到登录页 (from: ${pathname})`);
+
+      // 保存当前路径，登录后可以跳转回来
+      const redirectTo = pathname !== '/login' ? pathname : '/';
+      throw redirect(`/login?redirect=${encodeURIComponent(redirectTo)}`);
+    }
+
+    // 其他错误继续抛出
+    throw error;
+  }
+}
+
+/**
+ * 检查错误是否是 AuthenticationError
+ *
+ * @param error - 要检查的错误对象
+ * @returns 是否是 AuthenticationError
+ */
+export function isAuthenticationError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AuthenticationError';
+}
+
+/**
+ * 从 AuthenticationError 创建登录重定向
+ *
+ * @param pathname - 当前路径
+ * @returns Remix redirect Response
+ */
+export function redirectToLogin(pathname: string) {
+  const redirectTo = pathname !== '/login' ? pathname : '/';
+  return redirect(`/login?redirect=${encodeURIComponent(redirectTo)}`);
+}
diff --git a/auth_doc/API接口速查表.md b/auth_doc/API接口速查表.md
new file mode 100644
index 0000000..8e2b6c7
--- /dev/null
+++ b/auth_doc/API接口速查表.md
@@ -0,0 +1,435 @@
+# API接口速查表
+
+**版本**: v1.0
+**日期**: 2025-11-17
+**后端地址**: `http://172.16.0.55:8073`
+
+---
+
+## 📌 认证接口
+
+### 1. 统一登录接口
+
+**端点**: `POST /auth/login`
+
+**支持两种方式**:
+
+#### OAuth登录
+
+```typescript
+POST /auth/login
+Content-Type: application/json
+
+{
+  "userInfo": {
+    "sub": "user123",          // 必填
+    "username": "zhangsan",    // 可选
+    "nickname": "张三",        // 可选
+    "email": "...",            // 可选
+    "phone_number": "...",     // 可选
+    "ou_id": "dept001",        // 可选
+    "ou_name": "技术部",       // 可选
+    "is_leader": false         // 可选
+  },
+  "expiresIn": 3600,           // 必填
+  "area": "梅州"               // 可选，仅首次创建时保存
+}
+```
+
+#### 密码登录
+
+```typescript
+POST /auth/login
+Content-Type: application/json
+
+{
+  "username": "000",    // 实际是sub字段
+  "password": "admin06111"
+}
+```
+
+**成功响应**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "user_info": {
+      "user_id": "5",
+      "username": "admin",
+      "nick_name": "管理员",
+      "email": null,
+      "phone_number": null,
+      "ou_id": "default",
+      "ou_name": "未分配部门",
+      "is_leader": true,
+      "user_role": "admin",
+      "sub": "000"
+    }
+  }
+}
+```
+
+**失败响应**:
+
+```json
+{
+  "success": false,
+  "error": "用户名或密码错误"
+}
+```
+
+---
+
+## 📌 RBAC路由接口
+
+### 2. 获取用户路由
+
+**端点**: `GET /user/routes` 或 `GET /rbac/user/routes`
+
+**请求头**:
+
+```
+Authorization: Bearer {JWT_TOKEN}
+```
+
+**响应**:
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "user_id": 6,
+    "username": "001",
+    "routes": [
+      {
+        "id": 1,
+        "route_path": "/",
+        "route_name": "Layout",
+        "component": "layout/index",
+        "route_title": "入口页",
+        "icon": "el-icon-s-home",
+        "sort_order": 1,
+        "is_hidden": false,
+        "is_cache": true,
+        "children": [...]
+      }
+    ]
+  }
+}
+```
+
+### 3. 检查路由权限
+
+**端点**: `GET /rbac/check-route`
+
+**请求参数**:
+
+```
+route_path: /system/users
+```
+
+**请求头**:
+
+```
+Authorization: Bearer {JWT_TOKEN}
+```
+
+**响应**:
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "route_path": "/system/users",
+    "has_access": true
+  }
+}
+```
+
+### 4. 清除路由缓存
+
+**端点**: `POST /rbac/clear-routes-cache`
+
+**请求头**:
+
+```
+Authorization: Bearer {JWT_TOKEN}
+```
+
+**响应**:
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "message": "路由缓存已清除"
+  }
+}
+```
+
+---
+
+## 📌 PostgREST数据接口
+
+### 通用规则
+
+**所有数据表访问格式**:
+
+```
+GET    /{table_name}              # 查询
+POST   /{table_name}              # 创建
+PATCH  /{table_name}?{filter}     # 更新
+DELETE /{table_name}?{filter}     # 删除
+```
+
+**请求头**:
+
+```
+Authorization: Bearer {JWT_TOKEN}
+Content-Type: application/json
+```
+
+### PostgREST过滤操作符
+
+| 操作符 | 说明 | 示例 |
+|-------|------|------|
+| `eq` | 等于 | `id=eq.5` |
+| `neq` | 不等于 | `status=neq.1` |
+| `gt` | 大于 | `id=gt.10` |
+| `gte` | 大于等于 | `id=gte.10` |
+| `lt` | 小于 | `id=lt.100` |
+| `lte` | 小于等于 | `id=lte.100` |
+| `like` | 模糊匹配 | `title=like.*合同*` |
+| `ilike` | 不区分大小写模糊匹配 | `title=ilike.*word*` |
+| `in` | 在列表中 | `id=in.(1,2,3)` |
+| `is` | 是NULL | `deleted_at=is.null` |
+| `not.is` | 不是NULL | `deleted_at=not.is.null` |
+
+### 查询参数
+
+| 参数 | 说明 | 示例 |
+|-----|------|------|
+| `select` | 选择字段 | `select=id,title,created_at` |
+| `order` | 排序 | `order=created_at.desc` |
+| `limit` | 限制数量 | `limit=20` |
+| `offset` | 偏移量 | `offset=40` |
+
+---
+
+## 📌 常用数据表
+
+### documents（文档表）
+
+**查询文档列表**:
+
+```typescript
+GET /documents?user_id=eq.5&status=eq.0&select=id,title,created_at&order=created_at.desc&limit=20&offset=0
+```
+
+**创建文档**:
+
+```typescript
+POST /documents
+Content-Type: application/json
+
+{
+  "title": "测试文档",
+  "user_id": 5,
+  "status": 0
+}
+```
+
+**更新文档**:
+
+```typescript
+PATCH /documents?id=eq.123
+Content-Type: application/json
+
+{
+  "title": "新标题",
+  "status": 1
+}
+```
+
+**删除文档**:
+
+```typescript
+DELETE /documents?id=eq.123
+```
+
+### sso_users（用户表）
+
+**查询用户**:
+
+```typescript
+GET /sso_users?sub=eq.000&select=id,username,nick_name,email
+```
+
+**注意**: 普通用户无法直接访问 `sso_users` 表，需要通过特殊接口。
+
+### roles（角色表）
+
+**查询所有角色**:
+
+```typescript
+GET /roles?is_system_role=eq.true&select=id,role_key,role_name,priority&order=priority.desc
+```
+
+### user_role（用户-角色关联表）
+
+**查询用户角色**:
+
+```typescript
+GET /user_role?user_id=eq.5&select=role_id
+```
+
+### sys_routes（路由表）
+
+**查询所有路由**:
+
+```typescript
+GET /sys_routes?status=eq.0&deleted_at=is.null&select=id,route_path,route_title&order=sort_order
+```
+
+### role_route（角色-路由关联表）
+
+**查询角色路由**:
+
+```typescript
+GET /role_route?role_id=eq.1&select=route_id
+```
+
+---
+
+## 📌 完整示例
+
+### 登录 + 获取路由 + 查询数据
+
+```typescript
+import axios from 'axios';
+
+const API_BASE = 'http://172.16.0.55:8073';
+
+// 1. 登录
+const login = async () => {
+  const response = await axios.post(`${API_BASE}/auth/login`, {
+    username: '001',
+    password: 'gdyc06111'
+  });
+
+  const { access_token, user_info } = response.data.data;
+  localStorage.setItem('token', access_token);
+
+  return { token: access_token, userInfo: user_info };
+};
+
+// 2. 获取路由
+const fetchRoutes = async (token: string) => {
+  const response = await axios.get(`${API_BASE}/user/routes`, {
+    headers: { 'Authorization': `Bearer ${token}` }
+  });
+
+  return response.data.data.routes;
+};
+
+// 3. 查询文档（普通用户）
+const fetchDocuments = async (token: string, userId: string) => {
+  const response = await axios.get(`${API_BASE}/documents`, {
+    params: {
+      user_id: `eq.${userId}`,  // 只查自己的数据
+      status: `eq.0`,
+      select: 'id,title,created_at',
+      order: 'created_at.desc',
+      limit: 20,
+      offset: 0
+    },
+    headers: { 'Authorization': `Bearer ${token}` }
+  });
+
+  return response.data;
+};
+
+// 4. 创建文档
+const createDocument = async (token: string, userId: string) => {
+  const response = await axios.post(`${API_BASE}/documents`, {
+    title: '测试文档',
+    user_id: parseInt(userId),
+    status: 0
+  }, {
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    }
+  });
+
+  return response.data;
+};
+
+// 使用示例
+const main = async () => {
+  // 登录
+  const { token, userInfo } = await login();
+  console.log('登录成功:', userInfo);
+
+  // 获取路由
+  const routes = await fetchRoutes(token);
+  console.log('用户路由:', routes);
+
+  // 查询文档
+  const docs = await fetchDocuments(token, userInfo.user_id);
+  console.log('文档列表:', docs);
+
+  // 创建文档
+  const newDoc = await createDocument(token, userInfo.user_id);
+  console.log('新建文档:', newDoc);
+};
+
+main();
+```
+
+---
+
+## 📌 错误码对照表
+
+| HTTP状态码 | 说明 | 处理方式 |
+|-----------|------|---------|
+| 200 | 成功 | 正常处理 |
+| 400 | 请求参数错误 | 检查请求参数 |
+| 401 | 未授权/Token过期 | 重新登录 |
+| 403 | 无权限访问 | 提示用户无权限 |
+| 404 | 资源不存在 | 检查路径是否正确 |
+| 500 | 服务器错误 | 联系后端开发人员 |
+
+---
+
+## 📌 测试账号
+
+| 用户名 | 密码 | 角色 | 路由数 | 说明 |
+|--------|------|------|-------|------|
+| 000 | admin06111 | 超级管理员 | 29 | 所有权限 |
+| 001 | gdyc06111 | 普通用户 | 19 | 有限权限 |
+| jy001 | jyyc0814 | 系统管理员 | 29 | 管理员权限 |
+| mz001 | mzyc06111 | 系统管理员 | 29 | 管理员权限 |
+| yf001 | yfyc06111 | 系统管理员 | 29 | 管理员权限 |
+| cz001 | czyc06111 | 系统管理员 | 29 | 管理员权限 |
+
+---
+
+## 📌 快速链接
+
+- **完整对接文档**: `docs/RBAC/前端完整对接文档_RBAC与PostgREST.md`
+- **快速开始**: `docs/RBAC/前端快速开始_5分钟集成.md`
+- **用户管理**: `docs/RBAC/用户管理完整指南.md`
+- **RBAC总结**: `docs/RBAC/RBAC系统使用总结.md`
+
+---
+
+**创建时间**: 2025-11-17
+**维护者**: Claude Code
diff --git a/auth_doc/JWT管理文档.md b/auth_doc/JWT管理文档.md
new file mode 100644
index 0000000..914783e
--- /dev/null
+++ b/auth_doc/JWT管理文档.md
@@ -0,0 +1,1316 @@
+# JWT 管理文档
+
+DocAuditAI 系统 JWT（JSON Web Token）管理完整指南
+
+## 目录
+
+1. [JWT 概述](#jwt-概述)
+2. [JWT 生成机制](#jwt-生成机制)
+3. [JWT 验证流程](#jwt-验证流程)
+4. [JWT 配置说明](#jwt-配置说明)
+5. [JWT 刷新机制](#jwt-刷新机制)
+6. [JWT 吊销管理](#jwt-吊销管理)
+7. [前端对接指南](#前端对接指南)
+8. [安全最佳实践](#安全最佳实践)
+9. [常见问题](#常见问题)
+10. [故障排查](#故障排查)
+
+---
+
+## JWT 概述
+
+### 什么是 JWT？
+
+JWT（JSON Web Token）是一种开放标准（RFC 7519），用于在各方之间安全地传输信息。在 DocAuditAI 系统中，JWT 用于用户身份认证和授权。
+
+### JWT 结构
+
+JWT 由三部分组成，用 `.` 分隔：
+
+```
+Header.Payload.Signature
+```
+
+**示例**：
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1LCJ1c2VybmFtZSI6ImFkbWluIiwiZXhwIjoxNzMyMTY0MjA3fQ.Kz8fN3Y8Xp4QmW2vY6Jh9Lk0Rn1Tc3Uv5Wx6Yz7
+```
+
+#### 1. Header（头部）
+
+包含 Token 类型和签名算法：
+
+```json
+{
+  "alg": "HS256",
+  "typ": "JWT"
+}
+```
+
+#### 2. Payload（载荷）
+
+包含用户信息和权限数据：
+
+```json
+{
+  "user_id": 5,
+  "username": "admin",
+  "user_role": "系统管理员",
+  "ou_id": "000",
+  "ou_name": "test",
+  "exp": 1732164207,
+  "iat": 1732077807,
+  "aud": "docauditai:client"
+}
+```
+
+#### 3. Signature（签名）
+
+使用密钥对头部和载荷进行签名，防止篡改：
+
+```
+HMACSHA256(
+  base64UrlEncode(header) + "." +
+  base64UrlEncode(payload),
+  JWT_SECRET
+)
+```
+
+---
+
+## JWT 生成机制
+
+### 生成流程
+
+```
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│ 1. 用户登录  │ -->  │ 2. 验证凭据  │ -->  │ 3. 生成JWT   │ -->  │ 4. 返回Token │
+└─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
+```
+
+### 代码实现
+
+#### 1. 用户登录接口
+
+**接口**: `POST /auth/login`
+
+**请求体**:
+```json
+{
+  "username": "admin",
+  "password": "your_password"
+}
+```
+
+**响应**:
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "expires_in": 86400,
+  "user_info": {
+    "user_id": 5,
+    "username": "admin",
+    "roles": ["系统管理员"],
+    "ou_id": "000",
+    "ou_name": "test"
+  }
+}
+```
+
+#### 2. JWT 生成代码
+
+**位置**: `app/auth/jwt_handler.py`
+
+```python
+import jwt
+from datetime import datetime, timedelta
+import os
+
+def create_access_token(user_data: dict) -> str:
+    """
+    生成 JWT Access Token
+
+    Args:
+        user_data: 用户信息字典
+
+    Returns:
+        JWT Token 字符串
+    """
+    # JWT 配置
+    JWT_SECRET = os.getenv('JWT_SECRET', 'your-secret-key')
+    JWT_ALGORITHM = os.getenv('JWT_ALGORITHM', 'HS256')
+    JWT_EXPIRATION_HOURS = int(os.getenv('JWT_EXPIRATION_HOURS', 24))
+    JWT_AUDIENCE = os.getenv('JWT_AUDIENCE', 'docauditai:client')
+
+    # 计算过期时间
+    now = datetime.utcnow()
+    exp = now + timedelta(hours=JWT_EXPIRATION_HOURS)
+
+    # 构建 Payload
+    payload = {
+        'user_id': user_data['user_id'],
+        'username': user_data['username'],
+        'user_role': user_data.get('user_role', ''),
+        'ou_id': user_data.get('ou_id', ''),
+        'ou_name': user_data.get('ou_name', ''),
+        'exp': int(exp.timestamp()),
+        'iat': int(now.timestamp()),
+        'aud': JWT_AUDIENCE
+    }
+
+    # 生成 JWT
+    token = jwt.encode(
+        payload,
+        JWT_SECRET,
+        algorithm=JWT_ALGORITHM
+    )
+
+    return token
+```
+
+#### 3. 登录接口完整示例
+
+```python
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel
+
+router = APIRouter()
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+@router.post("/login")
+async def login(request: LoginRequest):
+    """用户登录接口"""
+
+    # 1. 验证用户名密码（示例：从数据库查询）
+    user = await verify_credentials(request.username, request.password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="用户名或密码错误"
+        )
+
+    # 2. 获取用户角色和权限
+    user_roles = await get_user_roles(user['id'])
+
+    # 3. 构建用户数据
+    user_data = {
+        'user_id': user['id'],
+        'username': user['username'],
+        'user_role': user_roles[0] if user_roles else '',
+        'ou_id': user['ou_id'],
+        'ou_name': user['ou_name']
+    }
+
+    # 4. 生成 JWT
+    access_token = create_access_token(user_data)
+
+    # 5. 返回响应
+    return {
+        'access_token': access_token,
+        'token_type': 'bearer',
+        'expires_in': 86400,  # 24小时（秒）
+        'user_info': user_data
+    }
+```
+
+---
+
+## JWT 验证流程
+
+### 双层验证机制
+
+DocAuditAI 采用**两层 JWT 验证机制**：
+
+#### 1. 中间件层（快速验证）
+
+**位置**: `app/middleware/jwt_auth.py`
+
+**目的**: 快速验证 Token 存在性，解析基本用户信息
+
+**流程**:
+```python
+async def jwt_auth_middleware(request: Request, call_next):
+    """JWT 认证中间件（宽松模式）"""
+
+    # 白名单路径（无需认证）
+    if request.url.path in WHITE_LIST:
+        return await call_next(request)
+
+    # 获取 Token
+    auth_header = request.headers.get('Authorization')
+    if not auth_header or not auth_header.startswith('Bearer '):
+        return JSONResponse(
+            status_code=401,
+            content={'detail': '缺少认证令牌'}
+        )
+
+    token = auth_header.replace('Bearer ', '')
+
+    try:
+        # 解析 JWT（不验证签名，提升性能）
+        payload = jwt.decode(
+            token,
+            options={"verify_signature": False}
+        )
+
+        # 设置用户信息到 request.state
+        request.state.current_user = {
+            'user_id': payload.get('user_id'),
+            'username': payload.get('username'),
+            'user_role': payload.get('user_role'),
+            'ou_id': payload.get('ou_id')
+        }
+
+    except jwt.DecodeError:
+        return JSONResponse(
+            status_code=401,
+            content={'detail': '无效的令牌格式'}
+        )
+
+    return await call_next(request)
+```
+
+**特点**:
+- ✅ 高性能：不验证签名，只解析 Token
+- ✅ 覆盖所有请求
+- ⚠️ 不验证 Token 是否被篡改
+- ⚠️ 不验证 Token 是否过期
+
+#### 2. 路由层（完整验证）
+
+**位置**: `app/auth/jwt_handler.py` 中的 `verify_token()` 依赖函数
+
+**目的**: 严格验证 Token 完整性和有效性
+
+**流程**:
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+import jwt
+import os
+
+security = HTTPBearer()
+
+async def verify_token(
+    credentials: HTTPAuthorizationCredentials = Depends(security)
+) -> dict:
+    """
+    完整 JWT 验证（路由层）
+
+    验证内容：
+    1. JWT 签名验证
+    2. 过期时间验证
+    3. Audience 验证
+    4. 必需字段验证
+
+    Returns:
+        用户信息字典
+
+    Raises:
+        HTTPException: Token 无效、过期或缺少必需字段
+    """
+    token = credentials.credentials
+    JWT_SECRET = os.getenv('JWT_SECRET', 'your-secret-key')
+    JWT_ALGORITHM = os.getenv('JWT_ALGORITHM', 'HS256')
+    JWT_AUDIENCE = os.getenv('JWT_AUDIENCE', 'docauditai:client')
+
+    try:
+        # 完整验证（包含签名、过期时间、audience）
+        payload = jwt.decode(
+            token,
+            JWT_SECRET,
+            algorithms=[JWT_ALGORITHM],
+            audience=JWT_AUDIENCE,
+            options={
+                "verify_signature": True,
+                "verify_exp": True,
+                "verify_aud": True
+            }
+        )
+
+        # 验证必需字段
+        required_fields = ['user_id', 'username', 'user_role', 'exp']
+        for field in required_fields:
+            if field not in payload:
+                raise HTTPException(
+                    status_code=401,
+                    detail=f'Token 缺少必需字段: {field}'
+                )
+
+        return payload
+
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(
+            status_code=401,
+            detail='令牌已过期，请重新登录'
+        )
+    except jwt.InvalidAudienceError:
+        raise HTTPException(
+            status_code=401,
+            detail='令牌受众验证失败'
+        )
+    except jwt.InvalidSignatureError:
+        raise HTTPException(
+            status_code=401,
+            detail='令牌签名验证失败'
+        )
+    except jwt.DecodeError:
+        raise HTTPException(
+            status_code=401,
+            detail='令牌格式错误'
+        )
+```
+
+**使用示例**:
+```python
+from fastapi import APIRouter, Depends
+from app.auth.jwt_handler import verify_token
+
+router = APIRouter()
+
+@router.get("/protected/resource")
+async def get_protected_resource(
+    current_user: dict = Depends(verify_token)
+):
+    """需要完整 JWT 验证的接口"""
+    return {
+        'message': '访问成功',
+        'user_id': current_user['user_id'],
+        'username': current_user['username']
+    }
+```
+
+**特点**:
+- ✅ 严格验证：签名、过期时间、受众、必需字段
+- ✅ 防篡改：验证 Token 签名
+- ✅ 防重放：验证过期时间
+- ⚠️ 性能较低：需要密钥解密和验证
+
+### 验证流程对比表
+
+| 验证内容 | 中间件层 | 路由层 |
+|---------|---------|--------|
+| Token 存在性 | ✅ | ✅ |
+| Token 格式正确 | ✅ | ✅ |
+| JWT 签名验证 | ❌ | ✅ |
+| 过期时间验证 | ❌ | ✅ |
+| Audience 验证 | ❌ | ✅ |
+| 必需字段验证 | ❌ | ✅ |
+| 性能 | 高 | 中 |
+| 使用场景 | 所有请求 | 敏感操作 |
+
+---
+
+## JWT 配置说明
+
+### 环境变量配置
+
+**位置**: `config/env.{port}` （例如 `config/env.8073`）
+
+```ini
+# JWT 配置
+JWT_SECRET=your-256-bit-secret-key-here
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_HOURS=24
+JWT_AUDIENCE=docauditai:client
+
+# PostgREST JWT 配置（不同于用户 JWT）
+PGRST_JWT_SECRET=different-secret-for-postgrest
+```
+
+### 配置项说明
+
+| 配置项 | 说明 | 默认值 | 推荐值 |
+|--------|------|--------|--------|
+| `JWT_SECRET` | JWT 签名密钥（256位） | `your-secret-key` | 随机生成的256位字符串 |
+| `JWT_ALGORITHM` | JWT 签名算法 | `HS256` | `HS256`（对称）或 `RS256`（非对称） |
+| `JWT_EXPIRATION_HOURS` | Token 有效期（小时） | `24` | `24`（生产环境） / `1`（测试环境） |
+| `JWT_AUDIENCE` | JWT 受众标识 | `docauditai:client` | `docauditai:client` |
+| `PGRST_JWT_SECRET` | PostgREST 内部 JWT 密钥 | - | 与 `JWT_SECRET` 不同的密钥 |
+
+### 密钥生成示例
+
+#### 方法1：Python 生成
+
+```python
+import secrets
+
+# 生成 256 位（32 字节）密钥
+jwt_secret = secrets.token_urlsafe(32)
+print(f"JWT_SECRET={jwt_secret}")
+```
+
+#### 方法2：OpenSSL 生成
+
+```bash
+openssl rand -base64 32
+```
+
+#### 方法3：在线生成
+
+访问：https://randomkeygen.com/ （选择 256-bit 密钥）
+
+### 安全注意事项
+
+⚠️ **重要**：
+1. **JWT_SECRET 必须保密**，不要提交到代码仓库
+2. **JWT_SECRET 和 PGRST_JWT_SECRET 必须不同**
+3. **生产环境使用强随机密钥**（至少 256 位）
+4. **定期轮换密钥**（建议每 90 天）
+
+---
+
+## JWT 刷新机制
+
+### 刷新策略
+
+DocAuditAI 支持两种 Token 刷新策略：
+
+#### 策略1：Token 自动续期（推荐）
+
+**原理**: Token 过期前 N 小时内访问任何接口，自动返回新 Token
+
+**配置**:
+```ini
+JWT_AUTO_REFRESH_ENABLED=true
+JWT_AUTO_REFRESH_THRESHOLD_HOURS=6
+```
+
+**响应头**:
+```
+X-New-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**前端处理**:
+```javascript
+// axios 响应拦截器
+apiClient.interceptors.response.use(
+  response => {
+    // 检查是否有新 Token
+    const newToken = response.headers['x-new-access-token'];
+    if (newToken) {
+      localStorage.setItem('access_token', newToken);
+      console.log('Token 已自动续期');
+    }
+    return response;
+  },
+  error => Promise.reject(error)
+);
+```
+
+#### 策略2：Refresh Token 机制
+
+**原理**: 登录时返回 Access Token + Refresh Token，Access Token 过期后使用 Refresh Token 获取新 Token
+
+**登录响应**:
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "expires_in": 86400
+}
+```
+
+**刷新接口**:
+
+**请求**: `POST /auth/refresh`
+
+**请求体**:
+```json
+{
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+**响应**:
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "expires_in": 86400
+}
+```
+
+**前端实现**:
+```javascript
+async function refreshAccessToken() {
+  const refreshToken = localStorage.getItem('refresh_token');
+  if (!refreshToken) {
+    // 跳转登录页
+    window.location.href = '/login';
+    return null;
+  }
+
+  try {
+    const response = await fetch('/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refresh_token: refreshToken })
+    });
+
+    if (response.ok) {
+      const data = await response.json();
+      localStorage.setItem('access_token', data.access_token);
+      return data.access_token;
+    } else {
+      // Refresh Token 也过期，跳转登录页
+      localStorage.removeItem('access_token');
+      localStorage.removeItem('refresh_token');
+      window.location.href = '/login';
+      return null;
+    }
+  } catch (error) {
+    console.error('Token 刷新失败:', error);
+    return null;
+  }
+}
+
+// axios 响应拦截器（自动刷新）
+apiClient.interceptors.response.use(
+  response => response,
+  async error => {
+    const originalRequest = error.config;
+
+    // 如果是 401 错误且未重试过
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      originalRequest._retry = true;
+
+      // 刷新 Token
+      const newToken = await refreshAccessToken();
+      if (newToken) {
+        // 使用新 Token 重试原请求
+        originalRequest.headers.Authorization = `Bearer ${newToken}`;
+        return apiClient(originalRequest);
+      }
+    }
+
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## JWT 吊销管理
+
+### 吊销场景
+
+1. **用户主动登出**
+2. **管理员强制下线用户**
+3. **密码修改后旧 Token 失效**
+4. **检测到异常登录**
+
+### 吊销实现方式
+
+#### 方式1：黑名单（推荐）
+
+**原理**: 将吊销的 Token 存入 Redis 黑名单，验证时检查
+
+**表结构**: `jwt_tokens` 表
+
+```sql
+CREATE TABLE jwt_tokens (
+    id SERIAL PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    token_jti VARCHAR(64) UNIQUE NOT NULL,  -- JWT ID
+    token_type VARCHAR(20) DEFAULT 'access',
+    revoked BOOLEAN DEFAULT false,
+    revoked_at TIMESTAMP,
+    expires_at TIMESTAMP NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_jwt_tokens_jti ON jwt_tokens(token_jti);
+CREATE INDEX idx_jwt_tokens_user_id ON jwt_tokens(user_id);
+```
+
+**生成 Token 时记录**:
+```python
+import uuid
+
+def create_access_token(user_data: dict) -> str:
+    # 生成唯一 JWT ID
+    jti = str(uuid.uuid4())
+
+    # Payload 中包含 jti
+    payload = {
+        'user_id': user_data['user_id'],
+        'username': user_data['username'],
+        'jti': jti,  # 唯一标识
+        'exp': int(exp.timestamp()),
+        'iat': int(now.timestamp()),
+        'aud': JWT_AUDIENCE
+    }
+
+    # 生成 Token
+    token = jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
+
+    # 记录到数据库
+    await record_token(
+        user_id=user_data['user_id'],
+        token_jti=jti,
+        expires_at=exp
+    )
+
+    return token
+```
+
+**验证 Token 时检查黑名单**:
+```python
+async def verify_token(token: str) -> dict:
+    # 解码 Token
+    payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
+    jti = payload.get('jti')
+
+    # 检查是否在黑名单
+    is_revoked = await check_token_revoked(jti)
+    if is_revoked:
+        raise HTTPException(
+            status_code=401,
+            detail='令牌已被吊销'
+        )
+
+    return payload
+
+async def check_token_revoked(jti: str) -> bool:
+    """检查 Token 是否已吊销"""
+    # 先查 Redis 缓存
+    cache_key = f"jwt:revoked:{jti}"
+    is_revoked = await redis_client.get(cache_key)
+    if is_revoked is not None:
+        return is_revoked == 'true'
+
+    # 查数据库
+    query = "SELECT revoked FROM jwt_tokens WHERE token_jti = $1"
+    result = await db_pool.fetchrow(query, jti)
+
+    if result and result['revoked']:
+        # 缓存到 Redis（24小时）
+        await redis_client.setex(cache_key, 86400, 'true')
+        return True
+
+    return False
+```
+
+**吊销 Token 接口**:
+
+**登出接口**: `POST /auth/logout`
+
+```python
+@router.post("/logout")
+async def logout(current_user: dict = Depends(verify_token)):
+    """用户登出"""
+    jti = current_user.get('jti')
+
+    # 吊销 Token
+    await revoke_token(jti)
+
+    return {'message': '登出成功'}
+
+async def revoke_token(jti: str):
+    """吊销指定 Token"""
+    query = """
+        UPDATE jwt_tokens
+        SET revoked = true, revoked_at = CURRENT_TIMESTAMP
+        WHERE token_jti = $1
+    """
+    await db_pool.execute(query, jti)
+
+    # 同步到 Redis
+    cache_key = f"jwt:revoked:{jti}"
+    await redis_client.setex(cache_key, 86400, 'true')
+```
+
+**强制下线用户**:
+
+```python
+async def revoke_user_all_tokens(user_id: int):
+    """吊销用户的所有 Token"""
+    query = """
+        UPDATE jwt_tokens
+        SET revoked = true, revoked_at = CURRENT_TIMESTAMP
+        WHERE user_id = $1 AND revoked = false
+        RETURNING token_jti
+    """
+    results = await db_pool.fetch(query, user_id)
+
+    # 同步到 Redis
+    for row in results:
+        cache_key = f"jwt:revoked:{row['token_jti']}"
+        await redis_client.setex(cache_key, 86400, 'true')
+```
+
+#### 方式2：Token 版本号
+
+**原理**: 为每个用户维护 Token 版本号，密码修改/强制下线时递增版本号
+
+**用户表新增字段**:
+```sql
+ALTER TABLE sso_users ADD COLUMN token_version INTEGER DEFAULT 1;
+```
+
+**Payload 中包含版本号**:
+```python
+payload = {
+    'user_id': user_data['user_id'],
+    'username': user_data['username'],
+    'token_version': user_data['token_version'],  # 版本号
+    'exp': int(exp.timestamp()),
+    'aud': JWT_AUDIENCE
+}
+```
+
+**验证时检查版本号**:
+```python
+async def verify_token(token: str) -> dict:
+    payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
+
+    # 获取用户当前版本号
+    current_version = await get_user_token_version(payload['user_id'])
+
+    # 检查版本号是否匹配
+    if payload.get('token_version', 0) != current_version:
+        raise HTTPException(
+            status_code=401,
+            detail='令牌版本已过期'
+        )
+
+    return payload
+```
+
+**密码修改后递增版本号**:
+```python
+async def change_password(user_id: int, new_password: str):
+    # 更新密码
+    await update_user_password(user_id, new_password)
+
+    # 递增 Token 版本号（使所有旧 Token 失效）
+    query = """
+        UPDATE sso_users
+        SET token_version = token_version + 1
+        WHERE id = $1
+    """
+    await db_pool.execute(query, user_id)
+```
+
+---
+
+## 前端对接指南
+
+### 1. 登录流程
+
+```javascript
+// 登录函数
+async function login(username, password) {
+  try {
+    const response = await fetch('/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password })
+    });
+
+    if (response.ok) {
+      const data = await response.json();
+
+      // 存储 Token
+      localStorage.setItem('access_token', data.access_token);
+      localStorage.setItem('user_info', JSON.stringify(data.user_info));
+
+      // 可选：存储 Refresh Token
+      if (data.refresh_token) {
+        localStorage.setItem('refresh_token', data.refresh_token);
+      }
+
+      // 跳转首页
+      window.location.href = '/';
+    } else {
+      const error = await response.json();
+      alert(`登录失败: ${error.detail}`);
+    }
+  } catch (error) {
+    console.error('登录错误:', error);
+    alert('网络错误，请稍后重试');
+  }
+}
+```
+
+### 2. 配置 Axios 拦截器
+
+```javascript
+import axios from 'axios';
+
+// 创建 Axios 实例
+const apiClient = axios.create({
+  baseURL: 'http://localhost:8000/api/v1',
+  headers: { 'Content-Type': 'application/json' }
+});
+
+// 请求拦截器：自动添加 Token
+apiClient.interceptors.request.use(
+  config => {
+    const token = localStorage.getItem('access_token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  },
+  error => Promise.reject(error)
+);
+
+// 响应拦截器：处理 401 错误
+apiClient.interceptors.response.use(
+  response => {
+    // 检查是否有新 Token（自动续期）
+    const newToken = response.headers['x-new-access-token'];
+    if (newToken) {
+      localStorage.setItem('access_token', newToken);
+    }
+    return response;
+  },
+  async error => {
+    const originalRequest = error.config;
+
+    // 401 错误处理
+    if (error.response?.status === 401) {
+      // 如果有 Refresh Token，尝试刷新
+      if (!originalRequest._retry && localStorage.getItem('refresh_token')) {
+        originalRequest._retry = true;
+        const newToken = await refreshAccessToken();
+        if (newToken) {
+          originalRequest.headers.Authorization = `Bearer ${newToken}`;
+          return apiClient(originalRequest);
+        }
+      }
+
+      // 否则跳转登录页
+      localStorage.clear();
+      window.location.href = '/login';
+    }
+
+    return Promise.reject(error);
+  }
+);
+
+export default apiClient;
+```
+
+### 3. 获取用户信息
+
+```javascript
+// 从 localStorage 获取
+function getCurrentUser() {
+  const userInfo = localStorage.getItem('user_info');
+  return userInfo ? JSON.parse(userInfo) : null;
+}
+
+// 从服务器获取最新用户信息
+async function fetchCurrentUser() {
+  try {
+    const response = await apiClient.get('/auth/me');
+    const userInfo = response.data;
+    localStorage.setItem('user_info', JSON.stringify(userInfo));
+    return userInfo;
+  } catch (error) {
+    console.error('获取用户信息失败:', error);
+    return null;
+  }
+}
+```
+
+### 4. 登出流程
+
+```javascript
+async function logout() {
+  try {
+    // 调用登出接口（吊销 Token）
+    await apiClient.post('/auth/logout');
+  } catch (error) {
+    console.error('登出接口调用失败:', error);
+  } finally {
+    // 清除本地存储
+    localStorage.clear();
+
+    // 跳转登录页
+    window.location.href = '/login';
+  }
+}
+```
+
+### 5. 路由守卫（Vue.js 示例）
+
+```javascript
+import { createRouter, createWebHistory } from 'vue-router';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/login', component: LoginPage },
+    { path: '/', component: HomePage, meta: { requiresAuth: true } },
+    { path: '/documents', component: DocumentList, meta: { requiresAuth: true } }
+  ]
+});
+
+// 全局路由守卫
+router.beforeEach((to, from, next) => {
+  const token = localStorage.getItem('access_token');
+
+  // 需要认证的路由
+  if (to.meta.requiresAuth && !token) {
+    next('/login');
+    return;
+  }
+
+  // 已登录用户访问登录页，跳转首页
+  if (to.path === '/login' && token) {
+    next('/');
+    return;
+  }
+
+  next();
+});
+
+export default router;
+```
+
+---
+
+## 安全最佳实践
+
+### 1. Token 存储
+
+**推荐方式**: `localStorage` 或 `sessionStorage`
+
+**不推荐**: Cookie（容易受到 CSRF 攻击）
+
+**示例**:
+```javascript
+// 存储
+localStorage.setItem('access_token', token);
+
+// 读取
+const token = localStorage.getItem('access_token');
+
+// 删除
+localStorage.removeItem('access_token');
+```
+
+### 2. HTTPS 传输
+
+⚠️ **生产环境必须使用 HTTPS**
+
+- Token 通过 HTTPS 加密传输
+- 防止中间人攻击（MITM）
+- 防止 Token 被窃取
+
+### 3. Token 有效期
+
+**推荐配置**:
+- **生产环境**: 24 小时
+- **测试环境**: 1-2 小时
+- **开发环境**: 7 天（方便调试）
+
+### 4. 密钥管理
+
+✅ **正确做法**:
+- 使用环境变量存储密钥
+- 生产环境使用强随机密钥
+- 定期轮换密钥（90 天）
+- 使用密钥管理服务（AWS KMS、Azure Key Vault）
+
+❌ **错误做法**:
+- 硬编码密钥在代码中
+- 将密钥提交到 Git
+- 使用弱密钥（如 `secret`、`12345`）
+
+### 5. Token 吊销
+
+✅ **必须实现**:
+- 用户登出时吊销 Token
+- 密码修改后吊销所有旧 Token
+- 检测到异常登录时吊销 Token
+- 管理员强制下线用户
+
+### 6. 防止 XSS 攻击
+
+✅ **防护措施**:
+- 前端对用户输入进行转义
+- 使用 CSP（Content Security Policy）
+- 避免在 URL 中传递 Token
+- 使用 HttpOnly Cookie（如果使用 Cookie 存储）
+
+### 7. 防止 CSRF 攻击
+
+✅ **防护措施**:
+- 使用 Bearer Token 而非 Cookie
+- 验证 Referer 头
+- 使用 CSRF Token
+
+---
+
+## 常见问题
+
+### Q1: Token 过期后如何处理？
+
+**A**: 使用 Refresh Token 机制或自动续期机制：
+
+```javascript
+// 响应拦截器
+apiClient.interceptors.response.use(
+  response => response,
+  async error => {
+    if (error.response?.status === 401 && !error.config._retry) {
+      error.config._retry = true;
+      const newToken = await refreshAccessToken();
+      if (newToken) {
+        error.config.headers.Authorization = `Bearer ${newToken}`;
+        return apiClient(error.config);
+      }
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+### Q2: 如何在多标签页间同步登录状态？
+
+**A**: 使用 `storage` 事件监听 `localStorage` 变化：
+
+```javascript
+window.addEventListener('storage', (event) => {
+  if (event.key === 'access_token') {
+    if (!event.newValue) {
+      // Token 被删除，其他标签页也跳转登录
+      window.location.href = '/login';
+    } else {
+      // Token 被更新，其他标签页也更新
+      console.log('Token 已在其他标签页更新');
+    }
+  }
+});
+```
+
+### Q3: JWT 和 Session 有什么区别？
+
+**A**:
+
+| 特性 | JWT | Session |
+|------|-----|---------|
+| 存储位置 | 客户端（localStorage） | 服务器（Redis/数据库） |
+| 状态 | 无状态 | 有状态 |
+| 可扩展性 | 高（无需共享状态） | 低（需要共享 Session） |
+| 吊销难度 | 高（需要黑名单） | 低（直接删除 Session） |
+| 性能 | 高（无需查询） | 低（需要查询 Session） |
+
+### Q4: 如何实现"记住我"功能？
+
+**A**: 使用长期有效的 Refresh Token：
+
+```javascript
+// 登录时勾选"记住我"
+async function login(username, password, rememberMe) {
+  const response = await fetch('/auth/login', {
+    method: 'POST',
+    body: JSON.stringify({
+      username,
+      password,
+      remember_me: rememberMe  // 传递"记住我"标志
+    })
+  });
+
+  const data = await response.json();
+
+  if (rememberMe) {
+    // 长期有效的 Refresh Token（30 天）
+    localStorage.setItem('refresh_token', data.refresh_token);
+  }
+}
+```
+
+### Q5: 如何检测 Token 是否被盗用？
+
+**A**: 记录 Token 使用的 IP 和 User-Agent，检测异常：
+
+```python
+@router.post("/login")
+async def login(request: Request, login_data: LoginRequest):
+    # 获取客户端信息
+    client_ip = request.client.host
+    user_agent = request.headers.get('User-Agent', '')
+
+    # 生成 Token 时记录
+    await record_token_metadata(
+        jti=jti,
+        client_ip=client_ip,
+        user_agent=user_agent
+    )
+```
+
+```python
+async def verify_token(request: Request, token: str):
+    # 检查 IP 和 User-Agent 是否匹配
+    current_ip = request.client.host
+    current_user_agent = request.headers.get('User-Agent', '')
+
+    metadata = await get_token_metadata(jti)
+
+    if metadata['client_ip'] != current_ip:
+        # IP 不匹配，可能被盗用
+        await log_security_event(
+            'Token used from different IP',
+            jti=jti,
+            original_ip=metadata['client_ip'],
+            current_ip=current_ip
+        )
+        # 可选：吊销 Token
+        await revoke_token(jti)
+        raise HTTPException(status_code=401, detail='Token 异常使用')
+```
+
+---
+
+## 故障排查
+
+### 问题1: Token 验证失败 "InvalidSignatureError"
+
+**原因**: JWT_SECRET 不一致
+
+**解决**:
+1. 检查 `config/env.{port}` 文件中的 `JWT_SECRET`
+2. 确保前端请求的后端实例使用相同的 `JWT_SECRET`
+3. 重新登录获取新 Token
+
+### 问题2: Token 过期 "ExpiredSignatureError"
+
+**原因**: Token 超过有效期
+
+**解决**:
+1. 使用 Refresh Token 刷新
+2. 重新登录
+3. 检查服务器时间是否正确（`exp` 基于 UTC 时间）
+
+### 问题3: Token 解码失败 "DecodeError"
+
+**原因**: Token 格式错误或被篡改
+
+**解决**:
+1. 检查 Token 是否完整（三部分用 `.` 分隔）
+2. 检查 Token 是否被 URL 编码（不应该编码）
+3. 检查前端是否正确存储和传递 Token
+
+### 问题4: 中间件不生效
+
+**原因**: 中间件注册顺序错误或白名单配置错误
+
+**解决**:
+1. 检查 `core/app.py` 中间件注册顺序（JWT 中间件应在路由之前）
+2. 检查白名单配置 `WHITE_LIST`
+3. 检查路由路径是否匹配
+
+### 问题5: PostgREST 返回 401
+
+**原因**: PostgREST 使用的 JWT Secret 不同
+
+**解决**:
+1. 确认 `PGRST_JWT_SECRET` 配置
+2. PostgREST 内部 JWT 由后端生成，前端不直接使用
+3. 检查 PostgREST 代理是否正确转换 Token
+
+### 调试技巧
+
+#### 1. 解码 Token（不验证签名）
+
+```python
+import jwt
+
+# 解码 Token（查看内容）
+token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+payload = jwt.decode(token, options={"verify_signature": False})
+print(payload)
+```
+
+```javascript
+// 前端解码 Token
+function decodeToken(token) {
+  const base64Url = token.split('.')[1];
+  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+  const jsonPayload = decodeURIComponent(atob(base64).split('').map(function(c) {
+    return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
+  }).join(''));
+
+  return JSON.parse(jsonPayload);
+}
+
+const token = localStorage.getItem('access_token');
+console.log(decodeToken(token));
+```
+
+#### 2. 检查 Token 是否过期
+
+```javascript
+function isTokenExpired(token) {
+  const payload = decodeToken(token);
+  const now = Math.floor(Date.now() / 1000);  // 当前时间（秒）
+  return payload.exp < now;
+}
+
+if (isTokenExpired(token)) {
+  console.log('Token 已过期');
+}
+```
+
+#### 3. 启用详细日志
+
+```ini
+# config/env.{port}
+LOG_LEVEL=DEBUG
+JWT_DEBUG_ENABLED=true
+```
+
+---
+
+## 附录
+
+### A. JWT Payload 字段完整说明
+
+| 字段 | 类型 | 必需 | 说明 | 示例 |
+|------|------|------|------|------|
+| `user_id` | integer | ✅ | 用户ID | `5` |
+| `username` | string | ✅ | 用户名 | `"admin"` |
+| `user_role` | string | ✅ | 用户角色 | `"系统管理员"` |
+| `ou_id` | string | ❌ | 组织单位ID | `"000"` |
+| `ou_name` | string | ❌ | 组织单位名称 | `"test"` |
+| `exp` | integer | ✅ | 过期时间（Unix 时间戳） | `1732164207` |
+| `iat` | integer | ✅ | 签发时间（Unix 时间戳） | `1732077807` |
+| `aud` | string | ✅ | 受众 | `"docauditai:client"` |
+| `jti` | string | ❌ | JWT ID（用于吊销） | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `token_version` | integer | ❌ | Token 版本号 | `1` |
+
+### B. HTTP 状态码说明
+
+| 状态码 | 说明 | 场景 |
+|--------|------|------|
+| 200 | 成功 | 登录成功、Token 验证成功 |
+| 401 | 未授权 | Token 缺失、无效、过期、被吊销 |
+| 403 | 禁止访问 | 权限不足 |
+| 422 | 验证错误 | 登录参数错误 |
+
+### C. 错误响应示例
+
+```json
+{
+  "detail": "令牌已过期，请重新登录",
+  "error_code": "TOKEN_EXPIRED",
+  "timestamp": "2025-11-17T10:30:00Z"
+}
+```
+
+---
+
+**文档版本**: v1.0
+**最后更新**: 2025-11-17
+**维护者**: DocAuditAI Team
diff --git a/auth_doc/前端完整对接文档_RBAC与PostgREST.md b/auth_doc/前端完整对接文档_RBAC与PostgREST.md
new file mode 100644
index 0000000..af3aa40
--- /dev/null
+++ b/auth_doc/前端完整对接文档_RBAC与PostgREST.md
@@ -0,0 +1,1655 @@
+# 前端完整对接文档 - RBAC与PostgREST
+
+**版本**: v2.0
+**日期**: 2025-11-17
+**目标**: Vue 3 + TypeScript + Pinia + Element Plus
+**后端地址**: `http://172.16.0.55:8073`
+
+---
+
+## 📋 目录
+
+1. [系统架构总览](#1-系统架构总览)
+2. [认证流程详解](#2-认证流程详解)
+3. [RBAC动态路由对接](#3-rbac动态路由对接)
+4. [PostgREST数据访问](#4-postgrest数据访问)
+5. [完整代码示例](#5-完整代码示例)
+6. [常见问题FAQ](#6-常见问题faq)
+
+---
+
+## 1. 系统架构总览
+
+### 1.1 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         前端 (Vue 3)                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │  登录页面    │  │  动态路由    │  │  数据列表    │       │
+│  │  /auth/login │  │  Vue Router  │  │  CRUD操作    │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+│         │                  │                  │              │
+│         │ ① 登录           │ ② 获取路由       │ ③ 数据请求   │
+└─────────┼──────────────────┼──────────────────┼──────────────┘
+          │                  │                  │
+          ▼                  ▼                  ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    后端 FastAPI (port 8073)                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │ POST /auth/  │  │ GET /user/   │  │ 全局异常处理 │       │
+│  │ login        │  │ routes       │  │ PostgREST转发│       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+│         │                  │                  │              │
+│         │                  │                  ▼              │
+│         │                  │         ┌──────────────┐        │
+│         │                  │         │  PostgREST   │        │
+│         │                  │         │  (port 3000) │        │
+│         │                  │         └──────────────┘        │
+│         ▼                  ▼                  │              │
+│  ┌──────────────────────────────────────────────┐           │
+│  │         PostgreSQL Database                  │           │
+│  │  - sso_users (用户表)                        │           │
+│  │  - roles (角色表)                            │           │
+│  │  - user_role (用户-角色关联)                 │           │
+│  │  - sys_routes (路由定义)                     │           │
+│  │  - role_route (角色-路由关联)                │           │
+│  │  - documents (文档表)                        │           │
+│  │  - ... (其他业务表)                          │           │
+│  └──────────────────────────────────────────────┘           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 三大核心功能
+
+| 功能 | 端点 | 说明 |
+|------|------|------|
+| **认证登录** | `POST /auth/login` | 支持OAuth和密码登录，返回JWT Token |
+| **动态路由** | `GET /user/routes` 或 `/rbac/user/routes` | 返回用户可访问的路由树 |
+| **数据访问** | `GET/POST/PATCH/DELETE /{table}` | PostgREST风格的数据库访问 |
+
+---
+
+## 2. 认证流程详解
+
+### 2.1 登录接口
+
+**端点**: `POST /auth/login`
+
+**支持两种登录方式**:
+1. **OAuth登录** - IDaaS统一认证（推荐）
+2. **密码登录** - 用户名密码认证
+
+#### 2.1.1 OAuth登录请求
+
+```typescript
+// OAuth登录请求格式
+interface OAuthLoginRequest {
+  userInfo: {
+    sub: string;              // 用户唯一标识（必填）
+    username?: string;        // 用户名/工号
+    nickname?: string;        // 昵称
+    email?: string;           // 邮箱
+    phone_number?: string;    // 手机号
+    ou_id?: string;           // 组织ID
+    ou_name?: string;         // 组织名称
+    is_leader?: boolean;      // 是否领导
+  };
+  expiresIn: number;          // Token过期时间（秒）
+  area?: string;              // 用户地区（仅首次创建时保存）
+}
+
+// 示例
+const oauthLogin = async (oauthData: any) => {
+  const response = await axios.post('http://172.16.0.55:8073/auth/login', {
+    userInfo: {
+      sub: 'user123',
+      username: 'zhangsan',
+      nickname: '张三',
+      email: 'zhangsan@example.com',
+      phone_number: '13800138000',
+      ou_id: 'dept001',
+      ou_name: '技术部',
+      is_leader: false
+    },
+    expiresIn: 3600,
+    area: '梅州'
+  });
+
+  return response.data;
+}
+```
+
+#### 2.1.2 密码登录请求
+
+```typescript
+// 密码登录请求格式
+interface PasswordLoginRequest {
+  username: string;   // 用户名（实际是sub字段）
+  password: string;   // 密码
+}
+
+// 示例
+const passwordLogin = async (username: string, password: string) => {
+  const response = await axios.post('http://172.16.0.55:8073/auth/login', {
+    username: username,  // 注意：这里实际传的是 sub
+    password: password
+  });
+
+  return response.data;
+}
+```
+
+#### 2.1.3 登录响应格式
+
+```typescript
+// 统一响应格式
+interface LoginResponse {
+  success: boolean;
+  data?: {
+    access_token: string;   // JWT Token
+    token_type: string;     // "Bearer"
+    expires_in: number;     // Token过期时间（秒）
+    user_info: {
+      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;    // 角色（admin/deptLeader/groupLeader/common）
+      sub: string;          // 用户唯一标识
+    };
+  };
+  error?: string;           // 错误信息
+}
+
+// 成功示例
+{
+  "success": true,
+  "data": {
+    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "user_info": {
+      "user_id": "5",
+      "username": "admin",
+      "nick_name": "管理员",
+      "email": null,
+      "phone_number": null,
+      "ou_id": "default",
+      "ou_name": "未分配部门",
+      "is_leader": true,
+      "user_role": "admin",
+      "sub": "000"
+    }
+  }
+}
+
+// 失败示例
+{
+  "success": false,
+  "error": "用户名或密码错误"
+}
+```
+
+### 2.2 登录状态管理
+
+#### 2.2.1 Pinia Store（stores/user.ts）
+
+```typescript
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+import axios from 'axios';
+import router from '@/router';
+
+interface UserInfo {
+  user_id: string;
+  username: string;
+  nick_name: string;
+  email?: string;
+  phone_number?: string;
+  ou_id: string;
+  ou_name: string;
+  is_leader: boolean;
+  user_role: string;
+  sub: string;
+}
+
+export const useUserStore = defineStore('user', () => {
+  // 状态
+  const token = ref<string>('');
+  const userInfo = ref<UserInfo | null>(null);
+  const routes = ref<any[]>([]);
+  const menuRoutes = ref<any[]>([]);
+  const hasLoadedRoutes = ref(false);
+
+  // 计算属性
+  const isLoggedIn = computed(() => !!token.value);
+  const isAdmin = computed(() => userInfo.value?.user_role === 'admin');
+
+  // 登录
+  const login = async (credentials: { username: string; password: string }) => {
+    try {
+      const response = await axios.post('/auth/login', credentials);
+
+      if (response.data.success) {
+        const { access_token, user_info } = response.data.data;
+
+        // 保存Token和用户信息
+        token.value = access_token;
+        userInfo.value = user_info;
+
+        // 持久化到localStorage
+        localStorage.setItem('token', access_token);
+        localStorage.setItem('userInfo', JSON.stringify(user_info));
+
+        // 设置axios默认header
+        axios.defaults.headers.common['Authorization'] = `Bearer ${access_token}`;
+
+        return { success: true };
+      } else {
+        return { success: false, error: response.data.error };
+      }
+    } catch (error: any) {
+      console.error('登录失败:', error);
+      return {
+        success: false,
+        error: error.response?.data?.error || '登录失败，请稍后重试'
+      };
+    }
+  };
+
+  // 登出
+  const logout = () => {
+    token.value = '';
+    userInfo.value = null;
+    routes.value = [];
+    menuRoutes.value = [];
+    hasLoadedRoutes.value = false;
+
+    localStorage.removeItem('token');
+    localStorage.removeItem('userInfo');
+    delete axios.defaults.headers.common['Authorization'];
+
+    router.push('/login');
+  };
+
+  // 从localStorage恢复登录状态
+  const restoreLoginState = () => {
+    const savedToken = localStorage.getItem('token');
+    const savedUserInfo = localStorage.getItem('userInfo');
+
+    if (savedToken && savedUserInfo) {
+      token.value = savedToken;
+      userInfo.value = JSON.parse(savedUserInfo);
+      axios.defaults.headers.common['Authorization'] = `Bearer ${savedToken}`;
+    }
+  };
+
+  // 获取用户路由（RBAC）
+  const fetchUserRoutes = async () => {
+    if (!token.value) {
+      throw new Error('未登录');
+    }
+
+    try {
+      const response = await axios.get('/user/routes');
+
+      if (response.data.code === 200) {
+        const routeData = response.data.data.routes;
+
+        routes.value = routeData;
+        menuRoutes.value = routeData.filter((r: any) => !r.is_hidden);
+        hasLoadedRoutes.value = true;
+
+        // 动态注册路由
+        registerDynamicRoutes(routeData);
+
+        return routeData;
+      } else {
+        throw new Error(response.data.msg || '获取路由失败');
+      }
+    } catch (error) {
+      console.error('获取用户路由失败:', error);
+      throw error;
+    }
+  };
+
+  // 动态注册路由到Vue Router
+  const registerDynamicRoutes = (routeList: any[]) => {
+    const transformRoute = (route: any): any => {
+      const transformed: any = {
+        path: route.route_path,
+        name: route.route_name,
+        meta: {
+          title: route.route_title,
+          icon: route.icon,
+          hidden: route.is_hidden,
+          cache: route.is_cache,
+          ...route.meta
+        }
+      };
+
+      // 组件路径映射
+      if (route.component) {
+        transformed.component = () => import(`@/views/${route.component}.vue`);
+      }
+
+      // 递归处理子路由
+      if (route.children && route.children.length > 0) {
+        transformed.children = route.children.map(transformRoute);
+      }
+
+      return transformed;
+    };
+
+    routeList.forEach(route => {
+      const transformedRoute = transformRoute(route);
+      router.addRoute(transformedRoute);
+    });
+  };
+
+  return {
+    token,
+    userInfo,
+    routes,
+    menuRoutes,
+    hasLoadedRoutes,
+    isLoggedIn,
+    isAdmin,
+    login,
+    logout,
+    restoreLoginState,
+    fetchUserRoutes
+  };
+});
+```
+
+#### 2.2.2 登录页面组件（views/Login.vue）
+
+```vue
+<template>
+  <div class="login-container">
+    <el-card class="login-card">
+      <h2>智慧法务系统</h2>
+      <el-form :model="loginForm" :rules="loginRules" ref="formRef">
+        <el-form-item prop="username">
+          <el-input
+            v-model="loginForm.username"
+            placeholder="请输入用户名"
+            prefix-icon="User"
+          />
+        </el-form-item>
+
+        <el-form-item prop="password">
+          <el-input
+            v-model="loginForm.password"
+            type="password"
+            placeholder="请输入密码"
+            prefix-icon="Lock"
+            @keyup.enter="handleLogin"
+          />
+        </el-form-item>
+
+        <el-form-item>
+          <el-button
+            type="primary"
+            :loading="loading"
+            @click="handleLogin"
+            style="width: 100%"
+          >
+            登 录
+          </el-button>
+        </el-form-item>
+      </el-form>
+    </el-card>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive } from 'vue';
+import { useRouter } from 'vue-router';
+import { useUserStore } from '@/stores/user';
+import { ElMessage } from 'element-plus';
+
+const router = useRouter();
+const userStore = useUserStore();
+
+const formRef = ref();
+const loading = ref(false);
+
+const loginForm = reactive({
+  username: '',
+  password: ''
+});
+
+const loginRules = {
+  username: [
+    { required: true, message: '请输入用户名', trigger: 'blur' }
+  ],
+  password: [
+    { required: true, message: '请输入密码', trigger: 'blur' }
+  ]
+};
+
+const handleLogin = async () => {
+  if (!formRef.value) return;
+
+  await formRef.value.validate(async (valid: boolean) => {
+    if (!valid) return;
+
+    loading.value = true;
+
+    try {
+      const result = await userStore.login({
+        username: loginForm.username,
+        password: loginForm.password
+      });
+
+      if (result.success) {
+        ElMessage.success('登录成功');
+
+        // 获取用户路由
+        await userStore.fetchUserRoutes();
+
+        // 跳转到首页
+        router.push('/home');
+      } else {
+        ElMessage.error(result.error || '登录失败');
+      }
+    } catch (error: any) {
+      ElMessage.error(error.message || '登录失败');
+    } finally {
+      loading.value = false;
+    }
+  });
+};
+</script>
+
+<style scoped>
+.login-container {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  height: 100vh;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+.login-card {
+  width: 400px;
+  padding: 20px;
+}
+
+h2 {
+  text-align: center;
+  margin-bottom: 30px;
+  color: #333;
+}
+</style>
+```
+
+---
+
+## 3. RBAC动态路由对接
+
+### 3.1 获取用户路由
+
+**端点**:
+- `GET /user/routes` （别名，推荐）
+- `GET /rbac/user/routes` （完整路径）
+
+**请求头**:
+```
+Authorization: Bearer {JWT_TOKEN}
+```
+
+**响应格式**:
+
+```typescript
+interface RouteResponse {
+  code: number;        // 200表示成功
+  msg: string;         // 操作消息
+  data: {
+    user_id: number;
+    username: string;
+    routes: RouteInfo[];  // 路由树
+  };
+}
+
+interface RouteInfo {
+  id: number;
+  route_path: string;     // 路由路径，如 "/home"
+  route_name: string;     // 路由名称，如 "Home"
+  component?: string;     // 组件路径，如 "views/Home.vue"
+  parent_id?: number;     // 父路由ID
+  route_title: string;    // 路由标题，用于菜单显示
+  icon?: string;          // 图标，如 "el-icon-house"
+  sort_order: number;     // 排序
+  is_hidden: boolean;     // 是否隐藏（不在菜单显示）
+  is_cache: boolean;      // 是否缓存
+  meta?: any;             // 其他元信息
+  children?: RouteInfo[]; // 子路由
+}
+```
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "user_id": 6,
+    "username": "001",
+    "routes": [
+      {
+        "id": 1,
+        "route_path": "/",
+        "route_name": "Layout",
+        "component": "layout/index",
+        "route_title": "入口页",
+        "icon": "el-icon-s-home",
+        "sort_order": 1,
+        "is_hidden": false,
+        "is_cache": true,
+        "children": [
+          {
+            "id": 2,
+            "route_path": "/home",
+            "route_name": "Home",
+            "component": "views/Home",
+            "parent_id": 1,
+            "route_title": "系统首页",
+            "icon": "el-icon-house",
+            "sort_order": 2,
+            "is_hidden": false,
+            "is_cache": true
+          },
+          {
+            "id": 3,
+            "route_path": "/dashboard",
+            "route_name": "Dashboard",
+            "component": "views/Dashboard",
+            "parent_id": 1,
+            "route_title": "工作台",
+            "icon": "el-icon-data-line",
+            "sort_order": 3,
+            "is_hidden": false,
+            "is_cache": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 3.2 路由注册最佳实践
+
+#### 3.2.1 路由守卫配置（router/index.ts）
+
+```typescript
+import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router';
+import { useUserStore } from '@/stores/user';
+import { ElMessage } from 'element-plus';
+
+// 静态路由（不需要权限的页面）
+const constantRoutes: RouteRecordRaw[] = [
+  {
+    path: '/login',
+    name: 'Login',
+    component: () => import('@/views/Login.vue'),
+    meta: { title: '登录', hidden: true }
+  },
+  {
+    path: '/404',
+    name: 'NotFound',
+    component: () => import('@/views/404.vue'),
+    meta: { title: '404', hidden: true }
+  }
+];
+
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL),
+  routes: constantRoutes
+});
+
+// 白名单（不需要登录的页面）
+const whiteList = ['/login', '/404'];
+
+// 全局前置守卫
+router.beforeEach(async (to, from, next) => {
+  const userStore = useUserStore();
+
+  // 恢复登录状态（从localStorage）
+  if (!userStore.isLoggedIn) {
+    userStore.restoreLoginState();
+  }
+
+  // 已登录
+  if (userStore.isLoggedIn) {
+    if (to.path === '/login') {
+      // 已登录，访问登录页 → 跳转到首页
+      next({ path: '/home' });
+    } else {
+      // 检查是否已加载路由
+      if (!userStore.hasLoadedRoutes) {
+        try {
+          // 获取用户路由
+          await userStore.fetchUserRoutes();
+
+          // 重新导航到目标路由（因为路由刚刚动态注册）
+          next({ ...to, replace: true });
+        } catch (error) {
+          console.error('获取路由失败:', error);
+          ElMessage.error('获取权限失败，请重新登录');
+          userStore.logout();
+          next({ path: '/login' });
+        }
+      } else {
+        // 路由已加载，正常放行
+        next();
+      }
+    }
+  } else {
+    // 未登录
+    if (whiteList.includes(to.path)) {
+      // 白名单内的页面，直接放行
+      next();
+    } else {
+      // 其他页面，跳转到登录
+      next({ path: '/login', query: { redirect: to.fullPath } });
+    }
+  }
+});
+
+// 全局后置钩子
+router.afterEach((to) => {
+  // 设置页面标题
+  document.title = (to.meta.title as string) || '智慧法务系统';
+});
+
+export default router;
+```
+
+### 3.3 菜单组件生成
+
+#### 3.3.1 侧边栏菜单组件（components/Sidebar.vue）
+
+```vue
+<template>
+  <el-menu
+    :default-active="activeMenu"
+    :collapse="isCollapse"
+    :unique-opened="true"
+    router
+  >
+    <sidebar-item
+      v-for="route in menuRoutes"
+      :key="route.route_path"
+      :item="route"
+    />
+  </el-menu>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useRoute } from 'vue-router';
+import { useUserStore } from '@/stores/user';
+import SidebarItem from './SidebarItem.vue';
+
+const route = useRoute();
+const userStore = useUserStore();
+
+const isCollapse = defineModel<boolean>('collapse', { default: false });
+
+const menuRoutes = computed(() => userStore.menuRoutes);
+const activeMenu = computed(() => route.path);
+</script>
+```
+
+#### 3.3.2 菜单项组件（components/SidebarItem.vue）
+
+```vue
+<template>
+  <!-- 有子菜单 -->
+  <el-sub-menu v-if="hasChildren" :index="item.route_path">
+    <template #title>
+      <el-icon v-if="item.icon"><component :is="item.icon" /></el-icon>
+      <span>{{ item.route_title }}</span>
+    </template>
+
+    <sidebar-item
+      v-for="child in item.children"
+      :key="child.route_path"
+      :item="child"
+    />
+  </el-sub-menu>
+
+  <!-- 无子菜单 -->
+  <el-menu-item v-else :index="item.route_path">
+    <el-icon v-if="item.icon"><component :is="item.icon" /></el-icon>
+    <template #title>{{ item.route_title }}</template>
+  </el-menu-item>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+interface RouteInfo {
+  route_path: string;
+  route_title: string;
+  icon?: string;
+  children?: RouteInfo[];
+}
+
+const props = defineProps<{
+  item: RouteInfo;
+}>();
+
+const hasChildren = computed(() => {
+  return props.item.children && props.item.children.length > 0;
+});
+</script>
+```
+
+---
+
+## 4. PostgREST数据访问
+
+### 4.1 PostgREST基础
+
+后端使用PostgREST提供RESTful API，所有数据库表都可以通过HTTP访问。
+
+**特点**:
+- 自动根据表结构生成API
+- 支持强大的过滤、排序、分页
+- 前端请求会被后端全局异常处理器拦截并转发到PostgREST
+
+### 4.2 请求格式
+
+#### 4.2.1 查询数据（GET）
+
+```typescript
+// 基础查询
+GET /{table_name}
+
+// 示例：查询文档列表
+const fetchDocuments = async () => {
+  const response = await axios.get('/documents', {
+    headers: {
+      'Authorization': `Bearer ${token}`
+    }
+  });
+  return response.data;
+};
+
+// 带过滤条件
+GET /documents?user_id=eq.5
+
+// 多个条件（AND）
+GET /documents?user_id=eq.5&status=eq.0
+
+// 选择字段
+GET /documents?select=id,title,created_at
+
+// 排序
+GET /documents?order=created_at.desc
+
+// 分页
+GET /documents?limit=20&offset=0
+
+// 组合查询
+GET /documents?user_id=eq.5&status=eq.0&select=id,title,created_at&order=created_at.desc&limit=20
+```
+
+#### PostgREST过滤操作符
+
+| 操作符 | 说明 | 示例 |
+|-------|------|------|
+| `eq` | 等于 | `id=eq.5` |
+| `neq` | 不等于 | `status=neq.1` |
+| `gt` | 大于 | `created_at=gt.2025-01-01` |
+| `gte` | 大于等于 | `id=gte.10` |
+| `lt` | 小于 | `updated_at=lt.2025-12-31` |
+| `lte` | 小于等于 | `id=lte.100` |
+| `like` | 模糊匹配 | `title=like.*合同*` |
+| `ilike` | 不区分大小写模糊匹配 | `title=ilike.*WORD*` |
+| `in` | 在列表中 | `id=in.(1,2,3,4,5)` |
+| `is` | 是NULL | `deleted_at=is.null` |
+| `not.is` | 不是NULL | `deleted_at=not.is.null` |
+
+#### 4.2.2 创建数据（POST）
+
+```typescript
+// 创建单条记录
+POST /{table_name}
+Content-Type: application/json
+
+{
+  "field1": "value1",
+  "field2": "value2"
+}
+
+// 示例：创建文档
+const createDocument = async (data: any) => {
+  const response = await axios.post('/documents', data, {
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    }
+  });
+  return response.data;
+};
+
+// 批量创建
+POST /documents
+Content-Type: application/json
+
+[
+  { "title": "文档1", "user_id": 5 },
+  { "title": "文档2", "user_id": 5 }
+]
+```
+
+#### 4.2.3 更新数据（PATCH）
+
+```typescript
+// 更新记录（需要过滤条件）
+PATCH /{table_name}?{filter}
+Content-Type: application/json
+
+{
+  "field1": "new_value"
+}
+
+// 示例：更新文档
+const updateDocument = async (id: number, data: any) => {
+  const response = await axios.patch(`/documents?id=eq.${id}`, data, {
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    }
+  });
+  return response.data;
+};
+```
+
+#### 4.2.4 删除数据（DELETE）
+
+```typescript
+// 删除记录（需要过滤条件）
+DELETE /{table_name}?{filter}
+
+// 示例：删除文档
+const deleteDocument = async (id: number) => {
+  const response = await axios.delete(`/documents?id=eq.${id}`, {
+    headers: {
+      'Authorization': `Bearer ${token}`
+    }
+  });
+  return response.data;
+};
+```
+
+### 4.3 Axios封装
+
+#### 4.3.1 请求拦截器（utils/request.ts）
+
+```typescript
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { ElMessage } from 'element-plus';
+import { useUserStore } from '@/stores/user';
+
+// 创建axios实例
+const service: AxiosInstance = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL || 'http://172.16.0.55:8073',
+  timeout: 30000
+});
+
+// 请求拦截器
+service.interceptors.request.use(
+  (config: AxiosRequestConfig) => {
+    const userStore = useUserStore();
+
+    // 自动添加Token
+    if (userStore.token) {
+      config.headers = config.headers || {};
+      config.headers['Authorization'] = `Bearer ${userStore.token}`;
+    }
+
+    return config;
+  },
+  (error) => {
+    console.error('请求错误:', error);
+    return Promise.reject(error);
+  }
+);
+
+// 响应拦截器
+service.interceptors.response.use(
+  (response: AxiosResponse) => {
+    const res = response.data;
+
+    // PostgREST返回数组或对象，不是统一格式
+    // 如果是数组或对象，直接返回
+    if (Array.isArray(res) || typeof res === 'object' && !res.code) {
+      return response;
+    }
+
+    // 统一格式的响应（code/msg/data）
+    if (res.code !== undefined) {
+      if (res.code === 200) {
+        return response;
+      } else {
+        ElMessage.error(res.msg || '操作失败');
+        return Promise.reject(new Error(res.msg || 'Error'));
+      }
+    }
+
+    return response;
+  },
+  (error) => {
+    console.error('响应错误:', error);
+
+    const userStore = useUserStore();
+
+    if (error.response) {
+      switch (error.response.status) {
+        case 401:
+          ElMessage.error('登录已过期，请重新登录');
+          userStore.logout();
+          break;
+        case 403:
+          ElMessage.error('没有权限访问');
+          break;
+        case 404:
+          ElMessage.error('请求的资源不存在');
+          break;
+        case 500:
+          ElMessage.error('服务器错误');
+          break;
+        default:
+          ElMessage.error(error.response.data?.msg || '请求失败');
+      }
+    } else {
+      ElMessage.error('网络错误，请检查网络连接');
+    }
+
+    return Promise.reject(error);
+  }
+);
+
+export default service;
+```
+
+#### 4.3.2 API封装示例（api/documents.ts）
+
+```typescript
+import request from '@/utils/request';
+
+// 文档接口类型定义
+export interface Document {
+  id: number;
+  title: string;
+  user_id: number;
+  status: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface DocumentQuery {
+  user_id?: number;
+  status?: number;
+  keyword?: string;
+  limit?: number;
+  offset?: number;
+  order?: string;
+}
+
+/**
+ * 查询文档列表
+ */
+export const getDocuments = (query: DocumentQuery = {}) => {
+  const params: any = {};
+
+  // 过滤条件
+  if (query.user_id !== undefined) {
+    params.user_id = `eq.${query.user_id}`;
+  }
+  if (query.status !== undefined) {
+    params.status = `eq.${query.status}`;
+  }
+  if (query.keyword) {
+    params.title = `like.*${query.keyword}*`;
+  }
+
+  // 排序
+  if (query.order) {
+    params.order = query.order;
+  } else {
+    params.order = 'created_at.desc';
+  }
+
+  // 分页
+  if (query.limit) {
+    params.limit = query.limit;
+  }
+  if (query.offset) {
+    params.offset = query.offset;
+  }
+
+  return request({
+    url: '/documents',
+    method: 'get',
+    params
+  });
+};
+
+/**
+ * 获取单个文档
+ */
+export const getDocument = (id: number) => {
+  return request({
+    url: '/documents',
+    method: 'get',
+    params: {
+      id: `eq.${id}`
+    }
+  });
+};
+
+/**
+ * 创建文档
+ */
+export const createDocument = (data: Partial<Document>) => {
+  return request({
+    url: '/documents',
+    method: 'post',
+    data
+  });
+};
+
+/**
+ * 更新文档
+ */
+export const updateDocument = (id: number, data: Partial<Document>) => {
+  return request({
+    url: `/documents?id=eq.${id}`,
+    method: 'patch',
+    data
+  });
+};
+
+/**
+ * 删除文档
+ */
+export const deleteDocument = (id: number) => {
+  return request({
+    url: `/documents?id=eq.${id}`,
+    method: 'delete'
+  });
+};
+```
+
+### 4.4 数据权限说明
+
+**重要**: 后端已禁用自动数据隔离，前端需要手动添加过滤条件！
+
+#### 普通用户（uploader角色）
+
+普通用户只能访问自己的数据，前端需要手动添加 `user_id` 过滤：
+
+```typescript
+// ❌ 错误：会查询所有用户的文档
+const docs = await axios.get('/documents');
+
+// ✅ 正确：只查询当前用户的文档
+const userStore = useUserStore();
+const userId = userStore.userInfo?.user_id;
+const docs = await axios.get(`/documents?user_id=eq.${userId}`);
+```
+
+#### 管理员用户
+
+管理员可以访问所有数据，无需添加 `user_id` 过滤。
+
+#### 最佳实践
+
+```typescript
+// 在API封装中自动处理权限
+export const getDocuments = (query: DocumentQuery = {}) => {
+  const userStore = useUserStore();
+  const params: any = {};
+
+  // 非管理员自动添加user_id过滤
+  if (!userStore.isAdmin) {
+    params.user_id = `eq.${userStore.userInfo?.user_id}`;
+  }
+
+  // 其他过滤条件
+  if (query.status !== undefined) {
+    params.status = `eq.${query.status}`;
+  }
+
+  return request({
+    url: '/documents',
+    method: 'get',
+    params
+  });
+};
+```
+
+---
+
+## 5. 完整代码示例
+
+### 5.1 项目结构
+
+```
+src/
+├── api/                    # API接口封装
+│   ├── auth.ts            # 认证接口
+│   ├── documents.ts       # 文档接口
+│   └── ...
+├── components/            # 组件
+│   ├── Sidebar.vue        # 侧边栏
+│   ├── SidebarItem.vue    # 菜单项
+│   └── ...
+├── router/                # 路由
+│   └── index.ts
+├── stores/                # Pinia状态管理
+│   └── user.ts            # 用户Store
+├── utils/                 # 工具函数
+│   └── request.ts         # Axios封装
+├── views/                 # 页面
+│   ├── Login.vue          # 登录页
+│   ├── Home.vue           # 首页
+│   └── ...
+├── App.vue
+└── main.ts
+```
+
+### 5.2 完整示例：文档列表页面
+
+```vue
+<template>
+  <div class="document-list">
+    <!-- 搜索栏 -->
+    <el-card class="search-card">
+      <el-form :inline="true" :model="searchForm">
+        <el-form-item label="关键词">
+          <el-input
+            v-model="searchForm.keyword"
+            placeholder="请输入文档标题"
+            clearable
+          />
+        </el-form-item>
+
+        <el-form-item label="状态">
+          <el-select v-model="searchForm.status" clearable placeholder="请选择状态">
+            <el-option label="全部" :value="undefined" />
+            <el-option label="正常" :value="0" />
+            <el-option label="已删除" :value="1" />
+          </el-select>
+        </el-form-item>
+
+        <el-form-item>
+          <el-button type="primary" @click="handleSearch">查询</el-button>
+          <el-button @click="handleReset">重置</el-button>
+          <el-button type="success" @click="handleCreate">新建</el-button>
+        </el-form-item>
+      </el-form>
+    </el-card>
+
+    <!-- 数据表格 -->
+    <el-card>
+      <el-table :data="documentList" v-loading="loading">
+        <el-table-column prop="id" label="ID" width="80" />
+        <el-table-column prop="title" label="标题" />
+        <el-table-column prop="status" label="状态" width="100">
+          <template #default="{ row }">
+            <el-tag :type="row.status === 0 ? 'success' : 'danger'">
+              {{ row.status === 0 ? '正常' : '已删除' }}
+            </el-tag>
+          </template>
+        </el-table-column>
+        <el-table-column prop="created_at" label="创建时间" width="180" />
+        <el-table-column label="操作" width="200" fixed="right">
+          <template #default="{ row }">
+            <el-button type="primary" size="small" @click="handleEdit(row)">
+              编辑
+            </el-button>
+            <el-button type="danger" size="small" @click="handleDelete(row)">
+              删除
+            </el-button>
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <!-- 分页 -->
+      <div class="pagination">
+        <el-pagination
+          v-model:current-page="pagination.page"
+          v-model:page-size="pagination.pageSize"
+          :total="pagination.total"
+          :page-sizes="[10, 20, 50, 100]"
+          layout="total, sizes, prev, pager, next, jumper"
+          @size-change="handleSearch"
+          @current-change="handleSearch"
+        />
+      </div>
+    </el-card>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, onMounted } from 'vue';
+import { ElMessage, ElMessageBox } from 'element-plus';
+import { getDocuments, deleteDocument, type Document } from '@/api/documents';
+
+// 搜索表单
+const searchForm = reactive({
+  keyword: '',
+  status: undefined as number | undefined
+});
+
+// 分页
+const pagination = reactive({
+  page: 1,
+  pageSize: 20,
+  total: 0
+});
+
+// 数据列表
+const documentList = ref<Document[]>([]);
+const loading = ref(false);
+
+// 查询列表
+const fetchList = async () => {
+  loading.value = true;
+
+  try {
+    const response = await getDocuments({
+      keyword: searchForm.keyword,
+      status: searchForm.status,
+      limit: pagination.pageSize,
+      offset: (pagination.page - 1) * pagination.pageSize
+    });
+
+    documentList.value = response.data;
+
+    // PostgREST返回Content-Range头表示总数
+    const contentRange = response.headers['content-range'];
+    if (contentRange) {
+      const total = parseInt(contentRange.split('/')[1]);
+      pagination.total = total;
+    }
+  } catch (error) {
+    ElMessage.error('查询失败');
+  } finally {
+    loading.value = false;
+  }
+};
+
+// 搜索
+const handleSearch = () => {
+  pagination.page = 1;
+  fetchList();
+};
+
+// 重置
+const handleReset = () => {
+  searchForm.keyword = '';
+  searchForm.status = undefined;
+  handleSearch();
+};
+
+// 新建
+const handleCreate = () => {
+  // 跳转到新建页面或打开对话框
+  console.log('新建文档');
+};
+
+// 编辑
+const handleEdit = (row: Document) => {
+  console.log('编辑文档', row);
+};
+
+// 删除
+const handleDelete = async (row: Document) => {
+  try {
+    await ElMessageBox.confirm('确定要删除该文档吗？', '提示', {
+      confirmButtonText: '确定',
+      cancelButtonText: '取消',
+      type: 'warning'
+    });
+
+    await deleteDocument(row.id);
+    ElMessage.success('删除成功');
+    fetchList();
+  } catch (error: any) {
+    if (error !== 'cancel') {
+      ElMessage.error('删除失败');
+    }
+  }
+};
+
+// 初始化
+onMounted(() => {
+  fetchList();
+});
+</script>
+
+<style scoped>
+.document-list {
+  padding: 20px;
+}
+
+.search-card {
+  margin-bottom: 20px;
+}
+
+.pagination {
+  margin-top: 20px;
+  display: flex;
+  justify-content: flex-end;
+}
+</style>
+```
+
+---
+
+## 6. 常见问题FAQ
+
+### 6.1 登录相关
+
+**Q: 登录后Token存在哪里？**
+
+A: Token存储在两个地方：
+1. Pinia Store的内存状态（`userStore.token`）
+2. localStorage持久化存储
+
+```typescript
+// 保存Token
+localStorage.setItem('token', access_token);
+
+// 读取Token
+const token = localStorage.getItem('token');
+
+// 删除Token（登出）
+localStorage.removeItem('token');
+```
+
+**Q: Token过期如何处理？**
+
+A: 后端返回401状态码时，前端自动登出并跳转到登录页：
+
+```typescript
+// 响应拦截器
+if (error.response?.status === 401) {
+  ElMessage.error('登录已过期，请重新登录');
+  userStore.logout();
+  router.push('/login');
+}
+```
+
+**Q: 如何实现自动登录？**
+
+A: 在应用启动时从localStorage恢复登录状态：
+
+```typescript
+// main.ts
+import { useUserStore } from '@/stores/user';
+
+const app = createApp(App);
+app.use(pinia);
+app.use(router);
+
+// 恢复登录状态
+const userStore = useUserStore();
+userStore.restoreLoginState();
+
+app.mount('#app');
+```
+
+### 6.2 路由相关
+
+**Q: 为什么要动态注册路由？**
+
+A: 因为不同用户有不同权限，看到的菜单和可访问的页面不同。通过动态注册路由：
+1. 提高安全性（用户只能访问有权限的页面）
+2. 减少打包体积（按需加载组件）
+3. 灵活配置权限（后端控制）
+
+**Q: 动态路由何时加载？**
+
+A: 在用户登录成功后，通过路由守卫自动加载：
+
+```typescript
+router.beforeEach(async (to, from, next) => {
+  if (userStore.isLoggedIn && !userStore.hasLoadedRoutes) {
+    await userStore.fetchUserRoutes(); // 加载路由
+    next({ ...to, replace: true });    // 重新导航
+  }
+});
+```
+
+**Q: `/user/routes` 和 `/rbac/user/routes` 有什么区别？**
+
+A: 两者功能完全相同，`/user/routes` 是别名路由，为了兼容前端直接调用。推荐使用 `/user/routes`。
+
+### 6.3 数据访问相关
+
+**Q: PostgREST查询如何分页？**
+
+A: 使用 `limit` 和 `offset` 参数：
+
+```typescript
+// 第1页，每页20条
+GET /documents?limit=20&offset=0
+
+// 第2页，每页20条
+GET /documents?limit=20&offset=20
+
+// 第3页，每页20条
+GET /documents?limit=20&offset=40
+```
+
+**Q: 如何获取总记录数？**
+
+A: PostgREST在响应头 `Content-Range` 返回总数：
+
+```typescript
+const response = await axios.get('/documents?limit=20&offset=0');
+const contentRange = response.headers['content-range'];
+// 格式: "0-19/156" 表示返回0-19条，总共156条
+const total = parseInt(contentRange.split('/')[1]); // 156
+```
+
+**Q: 如何实现模糊搜索？**
+
+A: 使用 `like` 或 `ilike` 操作符：
+
+```typescript
+// 搜索标题包含"合同"的文档
+GET /documents?title=like.*合同*
+
+// 不区分大小写
+GET /documents?title=ilike.*contract*
+```
+
+**Q: 普通用户只能看到自己的数据吗？**
+
+A: 是的！后端已禁用自动数据隔离，前端必须手动添加 `user_id` 过滤条件：
+
+```typescript
+const userStore = useUserStore();
+
+// 普通用户：只查询自己的数据
+if (!userStore.isAdmin) {
+  const docs = await axios.get(`/documents?user_id=eq.${userStore.userInfo.user_id}`);
+}
+
+// 管理员：查询所有数据
+if (userStore.isAdmin) {
+  const docs = await axios.get('/documents');
+}
+```
+
+### 6.4 权限控制
+
+**Q: 如何判断用户是否是管理员？**
+
+A: 通过 `user_role` 字段判断：
+
+```typescript
+const userStore = useUserStore();
+
+// 方式1：直接判断
+if (userStore.userInfo?.user_role === 'admin') {
+  console.log('管理员');
+}
+
+// 方式2：使用计算属性
+if (userStore.isAdmin) {
+  console.log('管理员');
+}
+```
+
+**Q: 如何控制按钮显示/隐藏？**
+
+A: 使用 `v-if` 指令：
+
+```vue
+<template>
+  <!-- 管理员才能看到删除按钮 -->
+  <el-button
+    v-if="userStore.isAdmin"
+    type="danger"
+    @click="handleDelete"
+  >
+    删除
+  </el-button>
+
+  <!-- 只有文档所有者才能编辑 -->
+  <el-button
+    v-if="document.user_id === userStore.userInfo?.user_id"
+    type="primary"
+    @click="handleEdit"
+  >
+    编辑
+  </el-button>
+</template>
+```
+
+**Q: 如何实现自定义权限指令？**
+
+A: 创建Vue自定义指令：
+
+```typescript
+// directives/permission.ts
+import { Directive } from 'vue';
+import { useUserStore } from '@/stores/user';
+
+export const permission: Directive = {
+  mounted(el, binding) {
+    const userStore = useUserStore();
+    const { value } = binding;
+
+    // value 是权限代码，如 'document:delete'
+    if (value && !userStore.userInfo?.permissions?.includes(value)) {
+      el.parentNode?.removeChild(el);
+    }
+  }
+};
+
+// main.ts
+import { permission } from '@/directives/permission';
+app.directive('permission', permission);
+
+// 使用
+<el-button v-permission="'document:delete'" type="danger">删除</el-button>
+```
+
+---
+
+## 7. 环境配置
+
+### 7.1 开发环境配置（.env.development）
+
+```env
+# API基础URL
+VITE_API_BASE_URL=http://172.16.0.55:8073
+
+# 应用端口
+VITE_PORT=5173
+
+# 是否开启Mock
+VITE_USE_MOCK=false
+```
+
+### 7.2 生产环境配置（.env.production）
+
+```env
+# API基础URL（生产环境）
+VITE_API_BASE_URL=https://api.example.com
+
+# 应用端口
+VITE_PORT=80
+
+# 是否开启Mock
+VITE_USE_MOCK=false
+```
+
+---
+
+## 8. 测试清单
+
+### 8.1 登录测试
+
+- [ ] 密码登录成功
+- [ ] 密码登录失败（错误提示）
+- [ ] OAuth登录成功
+- [ ] Token自动保存到localStorage
+- [ ] 刷新页面后自动恢复登录状态
+- [ ] Token过期自动跳转登录页
+
+### 8.2 路由测试
+
+- [ ] 登录后自动加载路由
+- [ ] 侧边栏菜单正确显示
+- [ ] 无权限路由无法访问（跳转404或登录页）
+- [ ] 路由跳转正常
+- [ ] 页面标题正确显示
+
+### 8.3 数据访问测试
+
+- [ ] 查询列表成功
+- [ ] 分页功能正常
+- [ ] 搜索过滤正常
+- [ ] 创建数据成功
+- [ ] 更新数据成功
+- [ ] 删除数据成功
+- [ ] 普通用户只能看到自己的数据
+- [ ] 管理员可以看到所有数据
+
+---
+
+## 9. 联系与支持
+
+如有问题，请联系后端团队或查看以下文档：
+
+- **RBAC系统总结**: `docs/RBAC/RBAC系统使用总结.md`
+- **用户管理指南**: `docs/RBAC/用户管理完整指南.md`
+- **角色权限配置**: `docs/RBAC/角色路由权限分配表.md`
+
+---
+
+**文档版本**: v2.0
+**创建时间**: 2025-11-17
+**维护者**: Claude Code
+**状态**: ✅ 完整对接文档，包含RBAC和PostgREST所有功能
diff --git a/auth_doc/前端对接文档-API端点列表.md b/auth_doc/前端对接文档-API端点列表.md
new file mode 100644
index 0000000..dc1e142
--- /dev/null
+++ b/auth_doc/前端对接文档-API端点列表.md
@@ -0,0 +1,121 @@
+# API端点列表
+
+## PostgREST代理端点
+
+所有PostgREST代理端点都位于 `/api/v1/postgrest/{table_name}`
+
+支持的HTTP方法：GET, POST, PATCH, DELETE
+
+### 文档管理模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| documents | /api/v1/postgrest/documents | 文档表 | document:document:view/create/update/delete |
+| document_types | /api/v1/postgrest/document_types | 文档类型（公共数据） | document:type:view/create/update/delete |
+| document_metadata | /api/v1/postgrest/document_metadata | 文档元数据 | document:metadata:view/create/update/delete |
+
+### 评查管理模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| evaluation_results | /api/v1/postgrest/evaluation_results | 评查结果 | evaluation:result:view/create/update/delete |
+| evaluation_points | /api/v1/postgrest/evaluation_points | 评查点配置 | evaluation:point:view/create/update/delete |
+| evaluation_point_categories | /api/v1/postgrest/evaluation_point_categories | 评查点分类 | evaluation:category:view/create/update/delete |
+| evaluation_rules | /api/v1/postgrest/evaluation_rules | 评查规则 | evaluation:rule:view/create/update/delete |
+
+### 交叉评查模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| cross_examination_tasks | /api/v1/postgrest/cross_examination_tasks | 交叉评查任务 | crossreview:task:view/create/update/delete |
+| cross_task_document_mapping | /api/v1/postgrest/cross_task_document_mapping | 任务-文档映射 | crossreview:mapping:view/create/update/delete |
+| cross_scoring_proposals | /api/v1/postgrest/cross_scoring_proposals | 评分提案 | crossreview:proposal:view/create/update/delete |
+| cross_proposal_votes | /api/v1/postgrest/cross_proposal_votes | 提案投票 | crossreview:vote:view/create/update/delete |
+
+### 用户管理模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| sso_users | /api/v1/postgrest/sso_users | 用户表 | system:user:view/create/update/delete |
+| user_role | /api/v1/postgrest/user_role | 用户-角色关联 | system:user_role:view/create/update/delete |
+
+### 系统管理模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| roles | /api/v1/postgrest/roles | 角色表 | system:role:view/create/update/delete |
+| sys_routes | /api/v1/postgrest/sys_routes | 系统路由（菜单） | system:route:view/create/update/delete |
+| role_route | /api/v1/postgrest/role_route | 角色-路由关联 | system:role_route:view/create/update/delete |
+
+### RBAC权限管理模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| permissions | /api/v1/postgrest/permissions | 权限定义 | system:permission:view/create/update/delete |
+| role_permissions | /api/v1/postgrest/role_permissions | 角色-权限关联 | system:role_permission:view/create/update/delete |
+| user_permissions | /api/v1/postgrest/user_permissions | 用户-权限关联 | system:user_permission:view/create/update/delete |
+| data_permission_rules | /api/v1/postgrest/data_permission_rules | 数据权限规则 | system:data_rule:view/create/update/delete |
+| permission_audit_logs | /api/v1/postgrest/permission_audit_logs | 权限审计日志 | system:audit_log:view/create/update/delete |
+| jwt_tokens | /api/v1/postgrest/jwt_tokens | JWT Token管理 | system:jwt_token:view/create/update/delete |
+
+### 报表统计模块
+
+| 表名 | 端点 | 说明 | 所需权限 |
+|------|------|------|---------|
+| statistics_summary | /api/v1/postgrest/statistics_summary | 统计汇总 | report:summary:view/create/update/delete |
+
+## FastAPI业务端点
+
+### 认证端点
+
+| 端点 | 方法 | 说明 | 认证 |
+|------|------|------|------|
+| /api/v1/auth/login | POST | 用户登录 | 否 |
+| /api/v1/auth/logout | POST | 用户登出 | 是 |
+| /api/v1/auth/refresh | POST | 刷新Token | 是 |
+
+### 文档业务端点（示例）
+
+| 端点 | 方法 | 说明 | 认证 |
+|------|------|------|------|
+| /api/v1/documents/{id}/ocr | POST | 文档OCR处理 | 是 |
+| /api/v1/documents/{id}/merge | POST | 合并PDF文档 | 是 |
+| /api/v1/documents/{id}/extract | POST | AI提取信息 | 是 |
+
+## 请求示例
+
+### GET请求示例
+```bash
+GET /api/v1/postgrest/documents?status=eq.active&limit=10&order=created_at.desc
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### POST请求示例
+```bash
+POST /api/v1/postgrest/documents
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{
+  "title": "新文档",
+  "content": "文档内容",
+  "status": "draft"
+}
+```
+
+### PATCH请求示例
+```bash
+PATCH /api/v1/postgrest/documents?id=eq.1936
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{
+  "status": "reviewed"
+}
+```
+
+### DELETE请求示例
+```bash
+DELETE /api/v1/postgrest/documents?id=eq.1936
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
diff --git a/auth_doc/前端对接文档-PostgREST查询参考.md b/auth_doc/前端对接文档-PostgREST查询参考.md
new file mode 100644
index 0000000..8ebcb3e
--- /dev/null
+++ b/auth_doc/前端对接文档-PostgREST查询参考.md
@@ -0,0 +1,316 @@
+# PostgREST查询参考
+
+## 过滤运算符完整列表
+
+### 比较运算符
+
+| 运算符 | 说明 | PostgREST语法 | JavaScript示例 |
+|--------|------|---------------|----------------|
+| eq | 等于 | `field=eq.value` | `{ field: 'eq.value' }` |
+| neq | 不等于 | `field=neq.value` | `{ field: 'neq.value' }` |
+| gt | 大于 | `field=gt.value` | `{ field: 'gt.100' }` |
+| gte | 大于等于 | `field=gte.value` | `{ field: 'gte.100' }` |
+| lt | 小于 | `field=lt.value` | `{ field: 'lt.100' }` |
+| lte | 小于等于 | `field=lte.value` | `{ field: 'lte.100' }` |
+
+### 模式匹配运算符
+
+| 运算符 | 说明 | PostgREST语法 | JavaScript示例 |
+|--------|------|---------------|----------------|
+| like | 模糊匹配（区分大小写） | `field=like.*pattern*` | `{ field: 'like.*测试*' }` |
+| ilike | 模糊匹配（不区分大小写） | `field=ilike.*pattern*` | `{ field: 'ilike.*TEST*' }` |
+
+**模式匹配通配符**:
+- `*`: 匹配任意字符（等同于SQL的`%`）
+- `_`: 匹配单个字符
+
+**示例**:
+```javascript
+// 查询标题以"合同"开头的文档
+{ title: 'like.合同*' }
+
+// 查询标题以"合同"结尾的文档
+{ title: 'like.*合同' }
+
+// 查询标题包含"合同"的文档
+{ title: 'like.*合同*' }
+
+// 不区分大小写查找
+{ title: 'ilike.*contract*' }
+```
+
+### 列表运算符
+
+| 运算符 | 说明 | PostgREST语法 | JavaScript示例 |
+|--------|------|---------------|----------------|
+| in | 在列表中 | `field=in.(value1,value2,...)` | `{ field: 'in.(active,pending)' }` |
+| cs | 包含（数组字段） | `field=cs.{value1,value2}` | `{ tags: 'cs.{重要,紧急}' }` |
+| cd | 被包含（数组字段） | `field=cd.{value1,value2}` | `{ tags: 'cd.{重要,紧急}' }` |
+| ov | 重叠（数组字段） | `field=ov.{value1,value2}` | `{ tags: 'ov.{重要,紧急}' }` |
+
+**示例**:
+```javascript
+// 查询状态为active或pending的文档
+{ status: 'in.(active,pending)' }
+
+// 查询ID在[1, 2, 3]中的文档
+{ id: 'in.(1,2,3)' }
+
+// 查询标签包含"重要"和"紧急"的文档（数组字段）
+{ tags: 'cs.{重要,紧急}' }
+```
+
+### Null检查运算符
+
+| 运算符 | 说明 | PostgREST语法 | JavaScript示例 |
+|--------|------|---------------|----------------|
+| is | 是null | `field=is.null` | `{ field: 'is.null' }` |
+| nt | 不是null | `field=nt.null` (或 `is.not.null`) | `{ field: 'nt.null' }` |
+
+**示例**:
+```javascript
+// 查询deleted_at为null的文档（未删除）
+{ deleted_at: 'is.null' }
+
+// 查询deleted_at不为null的文档（已删除）
+{ deleted_at: 'nt.null' }
+```
+
+## 排序
+
+### 单字段排序
+
+```javascript
+// 按创建时间升序
+{ order: 'created_at.asc' }
+
+// 按创建时间降序
+{ order: 'created_at.desc' }
+```
+
+### 多字段排序
+
+```javascript
+// 先按状态升序，再按创建时间降序
+{ order: 'status.asc,created_at.desc' }
+```
+
+## 分页
+
+### Limit和Offset
+
+```javascript
+// 每页10条，第1页
+{ limit: 10, offset: 0 }
+
+// 每页10条，第2页
+{ limit: 10, offset: 10 }
+
+// 每页20条，第3页
+{ limit: 20, offset: 40 }
+```
+
+### 获取总数
+
+PostgREST会在响应头中返回`Content-Range`，包含总记录数：
+
+```
+Content-Range: 0-9/50
+```
+表示：返回第0-9条记录，总共50条记录。
+
+**解析示例**:
+```javascript
+const response = await apiClient.get('/postgrest/documents', {
+  params: { limit: 10, offset: 0 }
+});
+
+const contentRange = response.headers['content-range'];
+const total = parseInt(contentRange.split('/')[1]); // 50
+```
+
+## 字段选择
+
+### 选择特定字段
+
+```javascript
+// 只返回id, title, status字段
+{ select: 'id,title,status' }
+```
+
+### 嵌套查询（外键关联）
+
+PostgREST支持嵌套查询，但DocAuditAI暂未启用此功能。
+
+## 高级查询
+
+### 逻辑运算符
+
+**注意**: 前端应避免使用`or`、`and`、`not`参数，这些参数由后端自动生成（用于数据范围和交叉评查权限）。
+
+### 复杂查询示例
+
+```javascript
+// 查询状态为active且创建时间在2025年之后的文档，按创建时间降序，每页10条
+const params = {
+  status: 'eq.active',
+  created_at: 'gte.2025-01-01',
+  order: 'created_at.desc',
+  limit: 10,
+  offset: 0
+};
+
+const response = await apiClient.get('/postgrest/documents', { params });
+```
+
+## 完整示例
+
+### 示例1：文档列表查询
+
+```javascript
+// 需求：查询标题包含"合同"、状态为active的文档，
+// 按创建时间降序排列，每页20条，第2页
+
+async function getDocumentList() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      title: 'ilike.*合同*',
+      status: 'eq.active',
+      order: 'created_at.desc',
+      limit: 20,
+      offset: 20  // 第2页
+    }
+  });
+
+  return {
+    data: response.data,
+    total: parseInt(response.headers['content-range'].split('/')[1])
+  };
+}
+```
+
+### 示例2：高级搜索
+
+```javascript
+// 需求：搜索2025年创建的、状态为active或pending的文档
+
+async function advancedSearch() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      status: 'in.(active,pending)',
+      created_at: 'gte.2025-01-01',
+      created_at: 'lt.2026-01-01',  // 注意：PostgREST会组合多个同名参数
+      order: 'created_at.desc'
+    }
+  });
+
+  return response.data;
+}
+```
+
+### 示例3：分页封装
+
+```javascript
+// 通用分页函数
+async function fetchPaginated(table, page, pageSize, filters = {}) {
+  const params = {
+    limit: pageSize,
+    offset: (page - 1) * pageSize,
+    ...filters
+  };
+
+  const response = await apiClient.get(`/postgrest/${table}`, { params });
+
+  const contentRange = response.headers['content-range'];
+  const total = contentRange ? parseInt(contentRange.split('/')[1]) : 0;
+
+  return {
+    data: response.data,
+    total: total,
+    page: page,
+    pageSize: pageSize,
+    totalPages: Math.ceil(total / pageSize)
+  };
+}
+
+// 使用示例
+const result = await fetchPaginated('documents', 1, 10, {
+  status: 'eq.active',
+  order: 'created_at.desc'
+});
+
+console.log(`共${result.total}条记录，第${result.page}/${result.totalPages}页`);
+```
+
+## 性能优化建议
+
+### 1. 始终使用分页
+
+```javascript
+// ✅ 好的做法
+{ limit: 10, offset: 0 }
+
+// ❌ 不好的做法（返回所有数据）
+{}
+```
+
+### 2. 只查询需要的字段
+
+```javascript
+// ✅ 好的做法（只查询id和title）
+{ select: 'id,title' }
+
+// ❌ 不好的做法（查询所有字段）
+{}
+```
+
+### 3. 使用索引字段进行过滤
+
+优先使用已建立索引的字段（如id, user_id, ou_id, status）进行过滤，提升查询性能。
+
+### 4. 避免过度模糊查询
+
+```javascript
+// ✅ 好的做法（明确的过滤条件）
+{ title: 'like.合同*' }
+
+// ❌ 不好的做法（前后通配符，性能差）
+{ title: 'like.*合同*' }
+```
+
+## 常见错误
+
+### 错误1：运算符拼写错误
+
+```javascript
+// ❌ 错误
+{ status: 'equal.active' }  // 应该是 eq
+
+// ✅ 正确
+{ status: 'eq.active' }
+```
+
+### 错误2：日期格式错误
+
+```javascript
+// ❌ 错误
+{ created_at: 'gte.2025/01/01' }  // 格式错误
+
+// ✅ 正确
+{ created_at: 'gte.2025-01-01' }  // ISO 8601格式
+```
+
+### 错误3：in运算符语法错误
+
+```javascript
+// ❌ 错误
+{ status: 'in.active,pending' }  // 缺少括号
+
+// ✅ 正确
+{ status: 'in.(active,pending)' }
+```
+
+## 参考资料
+
+- [PostgREST官方文档](https://postgrest.org/en/stable/)
+- [PostgREST API查询语法](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows)
diff --git a/auth_doc/前端对接文档-权限列表.md b/auth_doc/前端对接文档-权限列表.md
new file mode 100644
index 0000000..412383a
--- /dev/null
+++ b/auth_doc/前端对接文档-权限列表.md
@@ -0,0 +1,338 @@
+# 权限列表
+
+本文档列出DocAuditAI系统中所有权限及其对应的操作。
+
+## 权限键格式
+
+权限键格式：`{module}:{resource}:{action}`
+
+- **module**: 模块名称（如document, system, evaluation）
+- **resource**: 资源名称（如document, user, role）
+- **action**: 操作类型（view, create, update, delete等）
+
+## 文档管理模块 (document)
+
+| 权限键 | 说明 | 对应操作 |
+|--------|------|---------|
+| document:document:view | 查看文档 | GET /postgrest/documents |
+| document:document:create | 创建文档 | POST /postgrest/documents |
+| document:document:update | 更新文档 | PATCH /postgrest/documents |
+| document:document:delete | 删除文档 | DELETE /postgrest/documents |
+| document:type:view | 查看文档类型 | GET /postgrest/document_types |
+| document:type:create | 创建文档类型 | POST /postgrest/document_types |
+| document:type:update | 更新文档类型 | PATCH /postgrest/document_types |
+| document:type:delete | 删除文档类型 | DELETE /postgrest/document_types |
+| document:metadata:view | 查看文档元数据 | GET /postgrest/document_metadata |
+| document:metadata:create | 创建文档元数据 | POST /postgrest/document_metadata |
+| document:metadata:update | 更新文档元数据 | PATCH /postgrest/document_metadata |
+| document:metadata:delete | 删除文档元数据 | DELETE /postgrest/document_metadata |
+
+## 评查管理模块 (evaluation)
+
+| 权限键 | 说明 | 对应操作 |
+|--------|------|---------|
+| evaluation:result:view | 查看评查结果 | GET /postgrest/evaluation_results |
+| evaluation:result:create | 创建评查结果 | POST /postgrest/evaluation_results |
+| evaluation:result:update | 更新评查结果 | PATCH /postgrest/evaluation_results |
+| evaluation:result:delete | 删除评查结果 | DELETE /postgrest/evaluation_results |
+| evaluation:point:view | 查看评查点 | GET /postgrest/evaluation_points |
+| evaluation:point:create | 创建评查点 | POST /postgrest/evaluation_points |
+| evaluation:point:update | 更新评查点 | PATCH /postgrest/evaluation_points |
+| evaluation:point:delete | 删除评查点 | DELETE /postgrest/evaluation_points |
+| evaluation:category:view | 查看评查点分类 | GET /postgrest/evaluation_point_categories |
+| evaluation:category:create | 创建评查点分类 | POST /postgrest/evaluation_point_categories |
+| evaluation:category:update | 更新评查点分类 | PATCH /postgrest/evaluation_point_categories |
+| evaluation:category:delete | 删除评查点分类 | DELETE /postgrest/evaluation_point_categories |
+| evaluation:rule:view | 查看评查规则 | GET /postgrest/evaluation_rules |
+| evaluation:rule:create | 创建评查规则 | POST /postgrest/evaluation_rules |
+| evaluation:rule:update | 更新评查规则 | PATCH /postgrest/evaluation_rules |
+| evaluation:rule:delete | 删除评查规则 | DELETE /postgrest/evaluation_rules |
+
+## 交叉评查模块 (crossreview)
+
+| 权限键 | 说明 | 对应操作 |
+|--------|------|---------|
+| crossreview:task:view | 查看交叉评查任务 | GET /postgrest/cross_examination_tasks |
+| crossreview:task:create | 创建交叉评查任务 | POST /postgrest/cross_examination_tasks |
+| crossreview:task:update | 更新交叉评查任务 | PATCH /postgrest/cross_examination_tasks |
+| crossreview:task:delete | 删除交叉评查任务 | DELETE /postgrest/cross_examination_tasks |
+| crossreview:mapping:view | 查看任务文档映射 | GET /postgrest/cross_task_document_mapping |
+| crossreview:mapping:create | 创建任务文档映射 | POST /postgrest/cross_task_document_mapping |
+| crossreview:mapping:update | 更新任务文档映射 | PATCH /postgrest/cross_task_document_mapping |
+| crossreview:mapping:delete | 删除任务文档映射 | DELETE /postgrest/cross_task_document_mapping |
+| crossreview:proposal:view | 查看评分提案 | GET /postgrest/cross_scoring_proposals |
+| crossreview:proposal:create | 创建评分提案 | POST /postgrest/cross_scoring_proposals |
+| crossreview:proposal:update | 更新评分提案 | PATCH /postgrest/cross_scoring_proposals |
+| crossreview:proposal:delete | 删除评分提案 | DELETE /postgrest/cross_scoring_proposals |
+| crossreview:vote:view | 查看提案投票 | GET /postgrest/cross_proposal_votes |
+| crossreview:vote:create | 创建提案投票 | POST /postgrest/cross_proposal_votes |
+| crossreview:vote:update | 更新提案投票 | PATCH /postgrest/cross_proposal_votes |
+| crossreview:vote:delete | 删除提案投票 | DELETE /postgrest/cross_proposal_votes |
+
+## 系统管理模块 (system)
+
+| 权限键 | 说明 | 对应操作 |
+|--------|------|---------|
+| system:user:view | 查看用户 | GET /postgrest/sso_users |
+| system:user:create | 创建用户 | POST /postgrest/sso_users |
+| system:user:update | 更新用户 | PATCH /postgrest/sso_users |
+| system:user:delete | 删除用户 | DELETE /postgrest/sso_users |
+| system:role:view | 查看角色 | GET /postgrest/roles |
+| system:role:create | 创建角色 | POST /postgrest/roles |
+| system:role:update | 更新角色 | PATCH /postgrest/roles |
+| system:role:delete | 删除角色 | DELETE /postgrest/roles |
+| system:route:view | 查看系统路由 | GET /postgrest/sys_routes |
+| system:route:create | 创建系统路由 | POST /postgrest/sys_routes |
+| system:route:update | 更新系统路由 | PATCH /postgrest/sys_routes |
+| system:route:delete | 删除系统路由 | DELETE /postgrest/sys_routes |
+| system:user_role:view | 查看用户-角色关联 | GET /postgrest/user_role |
+| system:user_role:create | 创建用户-角色关联 | POST /postgrest/user_role |
+| system:user_role:update | 更新用户-角色关联 | PATCH /postgrest/user_role |
+| system:user_role:delete | 删除用户-角色关联 | DELETE /postgrest/user_role |
+| system:role_route:view | 查看角色-路由关联 | GET /postgrest/role_route |
+| system:role_route:create | 创建角色-路由关联 | POST /postgrest/role_route |
+| system:role_route:update | 更新角色-路由关联 | PATCH /postgrest/role_route |
+| system:role_route:delete | 删除角色-路由关联 | DELETE /postgrest/role_route |
+| system:permission:view | 查看权限定义 | GET /postgrest/permissions |
+| system:permission:create | 创建权限定义 | POST /postgrest/permissions |
+| system:permission:update | 更新权限定义 | PATCH /postgrest/permissions |
+| system:permission:delete | 删除权限定义 | DELETE /postgrest/permissions |
+| system:role_permission:view | 查看角色-权限关联 | GET /postgrest/role_permissions |
+| system:role_permission:create | 创建角色-权限关联 | POST /postgrest/role_permissions |
+| system:role_permission:update | 更新角色-权限关联 | PATCH /postgrest/role_permissions |
+| system:role_permission:delete | 删除角色-权限关联 | DELETE /postgrest/role_permissions |
+| system:user_permission:view | 查看用户-权限关联 | GET /postgrest/user_permissions |
+| system:user_permission:create | 创建用户-权限关联 | POST /postgrest/user_permissions |
+| system:user_permission:update | 更新用户-权限关联 | PATCH /postgrest/user_permissions |
+| system:user_permission:delete | 删除用户-权限关联 | DELETE /postgrest/user_permissions |
+| system:data_rule:view | 查看数据权限规则 | GET /postgrest/data_permission_rules |
+| system:data_rule:create | 创建数据权限规则 | POST /postgrest/data_permission_rules |
+| system:data_rule:update | 更新数据权限规则 | PATCH /postgrest/data_permission_rules |
+| system:data_rule:delete | 删除数据权限规则 | DELETE /postgrest/data_permission_rules |
+| system:audit_log:view | 查看审计日志 | GET /postgrest/permission_audit_logs |
+| system:audit_log:create | 创建审计日志 | POST /postgrest/permission_audit_logs |
+| system:audit_log:update | 更新审计日志 | PATCH /postgrest/permission_audit_logs |
+| system:audit_log:delete | 删除审计日志 | DELETE /postgrest/permission_audit_logs |
+| system:jwt_token:view | 查看JWT Token | GET /postgrest/jwt_tokens |
+| system:jwt_token:create | 创建JWT Token | POST /postgrest/jwt_tokens |
+| system:jwt_token:update | 更新JWT Token | PATCH /postgrest/jwt_tokens |
+| system:jwt_token:delete | 删除JWT Token | DELETE /postgrest/jwt_tokens |
+
+## 报表统计模块 (report)
+
+| 权限键 | 说明 | 对应操作 |
+|--------|------|---------|
+| report:summary:view | 查看统计汇总 | GET /postgrest/statistics_summary |
+| report:summary:create | 创建统计汇总 | POST /postgrest/statistics_summary |
+| report:summary:update | 更新统计汇总 | PATCH /postgrest/statistics_summary |
+| report:summary:delete | 删除统计汇总 | DELETE /postgrest/statistics_summary |
+
+## 预定义角色及其权限
+
+### 1. 系统管理员
+拥有所有权限（71个权限）
+
+### 2. 文档管理员
+- document:document:view
+- document:document:create
+- document:document:update
+- document:document:delete
+- document:type:view
+- document:type:create
+- document:type:update
+- document:type:delete
+- document:metadata:view
+- document:metadata:create
+- document:metadata:update
+- document:metadata:delete
+
+### 3. 文档审查员
+- document:document:view
+- document:document:update
+- evaluation:result:view
+- evaluation:result:create
+- evaluation:result:update
+- evaluation:point:view
+
+### 4. 交叉评查管理员
+- crossreview:task:view
+- crossreview:task:create
+- crossreview:task:update
+- crossreview:task:delete
+- crossreview:mapping:view
+- crossreview:mapping:create
+- crossreview:mapping:update
+- crossreview:mapping:delete
+- crossreview:proposal:view
+- crossreview:proposal:create
+- crossreview:proposal:update
+- crossreview:vote:view
+- crossreview:vote:create
+- crossreview:vote:update
+
+### 5. 交叉评查参与者
+- crossreview:task:view
+- crossreview:mapping:view
+- crossreview:proposal:view
+- crossreview:proposal:create
+- crossreview:vote:view
+- crossreview:vote:create
+
+### 6. 评价点管理员
+- evaluation:point:view
+- evaluation:point:create
+- evaluation:point:update
+- evaluation:point:delete
+- evaluation:category:view
+- evaluation:category:create
+- evaluation:category:update
+- evaluation:category:delete
+- evaluation:rule:view
+- evaluation:rule:create
+- evaluation:rule:update
+- evaluation:rule:delete
+
+### 7. 报表查看员
+- report:summary:view
+- document:document:view
+- evaluation:result:view
+
+### 8. 普通用户
+- document:document:view
+- document:type:view
+- evaluation:point:view
+- evaluation:category:view
+
+### 9. 审计员
+- system:audit_log:view
+- document:document:view
+- evaluation:result:view
+- crossreview:task:view
+
+## 前端权限控制示例
+
+### 示例1：按钮权限控制
+
+```vue
+<template>
+  <!-- 只有拥有document:document:delete权限的用户才能看到删除按钮 -->
+  <button v-permission="'document:document:delete'" @click="deleteDoc">
+    删除文档
+  </button>
+
+  <!-- 只有系统管理员才能看到 -->
+  <button v-role="'系统管理员'" @click="showAdminPanel">
+    管理面板
+  </button>
+</template>
+```
+
+### 示例2：菜单权限控制
+
+```javascript
+// 菜单配置（根据权限动态生成）
+const menuConfig = [
+  {
+    name: '文档管理',
+    permission: 'document:document:view',
+    children: [
+      { name: '文档列表', permission: 'document:document:view', path: '/documents' },
+      { name: '新建文档', permission: 'document:document:create', path: '/documents/new' }
+    ]
+  },
+  {
+    name: '评查管理',
+    permission: 'evaluation:point:view',
+    children: [
+      { name: '评查点配置', permission: 'evaluation:point:view', path: '/evaluation/points' },
+      { name: '评查结果', permission: 'evaluation:result:view', path: '/evaluation/results' }
+    ]
+  },
+  {
+    name: '系统管理',
+    role: '系统管理员',  // 只有系统管理员才能看到
+    children: [
+      { name: '用户管理', permission: 'system:user:view', path: '/system/users' },
+      { name: '角色管理', permission: 'system:role:view', path: '/system/roles' }
+    ]
+  }
+];
+
+// 过滤菜单（根据用户权限）
+function filterMenuByPermission(menu, userPermissions, userRoles) {
+  return menu.filter(item => {
+    // 检查角色
+    if (item.role && !userRoles.includes(item.role)) {
+      return false;
+    }
+
+    // 检查权限
+    if (item.permission && !userPermissions.includes(item.permission)) {
+      return false;
+    }
+
+    // 递归过滤子菜单
+    if (item.children) {
+      item.children = filterMenuByPermission(item.children, userPermissions, userRoles);
+    }
+
+    return true;
+  });
+}
+```
+
+### 示例3：路由守卫
+
+```javascript
+// router.js
+import { createRouter, createWebHistory } from 'vue-router';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/documents',
+      component: DocumentList,
+      meta: { permission: 'document:document:view' }
+    },
+    {
+      path: '/system/users',
+      component: UserManagement,
+      meta: { role: '系统管理员' }
+    }
+  ]
+});
+
+// 全局路由守卫
+router.beforeEach((to, from, next) => {
+  const userInfo = JSON.parse(localStorage.getItem('user_info') || '{}');
+
+  // 检查角色
+  if (to.meta.role && !userInfo.roles?.includes(to.meta.role)) {
+    alert('无权访问此页面');
+    next('/');
+    return;
+  }
+
+  // 检查权限（简化版，实际应维护权限列表）
+  if (to.meta.permission) {
+    // TODO: 检查用户是否有该权限
+  }
+
+  next();
+});
+```
+
+## 注意事项
+
+1. **权限检查由后端强制执行**
+   即使前端绕过权限控制，后端也会拒绝无权请求。
+
+2. **前端权限控制是为了提升用户体验**
+   隐藏用户无权操作的按钮和菜单，避免用户点击后被拒绝。
+
+3. **定期同步权限列表**
+   登录时从后端获取用户的完整权限列表，存储到前端状态管理中。
+
+4. **角色权限继承**
+   用户通过角色继承权限，也可以直接分配权限（优先级高于角色）。
diff --git a/auth_doc/前端对接文档.md b/auth_doc/前端对接文档.md
new file mode 100644
index 0000000..385862a
--- /dev/null
+++ b/auth_doc/前端对接文档.md
@@ -0,0 +1,1562 @@
+# DocAuditAI 前端对接文档
+
+**版本**: v1.0
+**最后更新**: 2025-11-17
+**适用范围**: 前端开发人员
+
+---
+
+## 目录
+
+1. [系统概述](#1-系统概述)
+2. [认证与授权](#2-认证与授权)
+3. [PostgREST API使用](#3-postgrest-api使用)
+4. [RBAC权限系统](#4-rbac权限系统)
+5. [数据范围过滤](#5-数据范围过滤)
+6. [交叉评查权限](#6-交叉评查权限)
+7. [错误处理](#7-错误处理)
+8. [常用示例](#8-常用示例)
+9. [最佳实践](#9-最佳实践)
+10. [故障排查](#10-故障排查)
+
+---
+
+## 1. 系统概述
+
+### 1.1 架构概览
+
+DocAuditAI采用三层架构：
+
+```
+┌─────────────┐
+│  前端应用   │  Vue.js / React / Angular
+└─────────────┘
+      ↓ HTTPS
+┌─────────────┐
+│  FastAPI    │  认证、权限检查、业务逻辑
+│  (端口8000) │
+└─────────────┘
+      ↓
+┌─────────────┐
+│  PostgREST  │  直接数据库访问（经过RBAC过滤）
+│  (端口3000) │
+└─────────────┘
+      ↓
+┌─────────────┐
+│ PostgreSQL  │  数据存储
+│  (端口5432) │
+└─────────────┘
+```
+
+### 1.2 API端点
+
+- **FastAPI主应用**: `http://localhost:8000/api/v1/`
+- **PostgREST代理**: `http://localhost:8000/api/v1/postgrest/`
+- **认证端点**: `http://localhost:8000/api/v1/auth/`
+
+### 1.3 技术栈要求
+
+**前端推荐技术栈**:
+- **HTTP客户端**: Axios (推荐) 或 Fetch API
+- **状态管理**: Vuex / Pinia (Vue) 或 Redux (React)
+- **UI框架**: Element Plus / Ant Design / Material-UI
+
+---
+
+## 2. 认证与授权
+
+### 2.1 JWT认证流程
+
+DocAuditAI使用JWT（JSON Web Token）进行用户认证。
+
+#### 登录流程
+
+```mermaid
+sequenceDiagram
+    participant 前端
+    participant FastAPI
+    participant 数据库
+
+    前端->>FastAPI: POST /api/v1/auth/login {username, password}
+    FastAPI->>数据库: 验证用户凭据
+    数据库-->>FastAPI: 用户信息 + 权限
+    FastAPI-->>前端: {access_token, token_type, user_info}
+    前端->>前端: 存储access_token到localStorage
+```
+
+#### 登录示例
+
+**请求**:
+```javascript
+// JavaScript/TypeScript
+import axios from 'axios';
+
+const API_BASE_URL = 'http://localhost:8000/api/v1';
+
+async function login(username, password) {
+  try {
+    const response = await axios.post(`${API_BASE_URL}/auth/login`, {
+      username,
+      password
+    });
+
+    // 保存Token
+    localStorage.setItem('access_token', response.data.access_token);
+    localStorage.setItem('user_info', JSON.stringify(response.data.user_info));
+
+    return response.data;
+  } catch (error) {
+    console.error('登录失败:', error.response?.data || error.message);
+    throw error;
+  }
+}
+
+// 使用示例
+login('user@example.com', 'password123')
+  .then(data => {
+    console.log('登录成功:', data.user_info);
+  })
+  .catch(err => {
+    console.error('登录失败');
+  });
+```
+
+**成功响应** (HTTP 200):
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "user_info": {
+    "user_id": 9,
+    "username": "云浮测试",
+    "ou_id": "yunfu002",
+    "ou_name": "云浮测试用户账户",
+    "roles": ["文档审查员", "普通用户"]
+  }
+}
+```
+
+**失败响应** (HTTP 401):
+```json
+{
+  "detail": "用户名或密码错误"
+}
+```
+
+### 2.2 请求认证
+
+所有需要认证的API请求都必须在请求头中携带JWT Token。
+
+#### Axios全局配置（推荐）
+
+```javascript
+// axios-instance.js
+import axios from 'axios';
+
+const API_BASE_URL = 'http://localhost:8000/api/v1';
+
+// 创建Axios实例
+const apiClient = axios.create({
+  baseURL: API_BASE_URL,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+});
+
+// 请求拦截器：自动添加Token
+apiClient.interceptors.request.use(
+  config => {
+    const token = localStorage.getItem('access_token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  },
+  error => Promise.reject(error)
+);
+
+// 响应拦截器：处理认证错误
+apiClient.interceptors.response.use(
+  response => response,
+  error => {
+    if (error.response?.status === 401) {
+      // Token过期或无效，跳转到登录页
+      localStorage.removeItem('access_token');
+      localStorage.removeItem('user_info');
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+
+export default apiClient;
+```
+
+**使用示例**:
+```javascript
+import apiClient from './axios-instance';
+
+// 查询文档列表（自动携带Token）
+async function getDocuments() {
+  const response = await apiClient.get('/postgrest/documents?limit=10');
+  return response.data;
+}
+```
+
+### 2.3 Token刷新
+
+JWT Token有效期为24小时。Token过期后需要重新登录。
+
+**检查Token是否过期**:
+```javascript
+function isTokenExpired() {
+  const token = localStorage.getItem('access_token');
+  if (!token) return true;
+
+  try {
+    const payload = JSON.parse(atob(token.split('.')[1]));
+    const exp = payload.exp * 1000; // 转换为毫秒
+    return Date.now() >= exp;
+  } catch (e) {
+    return true;
+  }
+}
+
+// 定期检查Token（可选）
+setInterval(() => {
+  if (isTokenExpired()) {
+    alert('登录已过期，请重新登录');
+    window.location.href = '/login';
+  }
+}, 60000); // 每分钟检查一次
+```
+
+### 2.4 退出登录
+
+```javascript
+async function logout() {
+  try {
+    // 调用后端登出接口（可选，如果后端有黑名单机制）
+    await apiClient.post('/auth/logout');
+  } catch (error) {
+    console.error('登出失败:', error);
+  } finally {
+    // 清除本地存储
+    localStorage.removeItem('access_token');
+    localStorage.removeItem('user_info');
+    window.location.href = '/login';
+  }
+}
+```
+
+---
+
+## 3. PostgREST API使用
+
+### 3.1 PostgREST代理概述
+
+PostgREST代理提供了对数据库表的直接RESTful访问，**自动集成RBAC权限检查和数据范围过滤**。
+
+**基础URL**: `/api/v1/postgrest/{table_name}`
+
+**支持的HTTP方法**:
+- `GET`: 查询数据
+- `POST`: 创建数据
+- `PATCH`: 更新数据
+- `DELETE`: 删除数据
+
+### 3.2 查询操作 (GET)
+
+#### 3.2.1 查询所有记录
+
+```javascript
+// 查询所有文档（自动应用数据范围过滤）
+async function getAllDocuments() {
+  const response = await apiClient.get('/postgrest/documents');
+  return response.data;
+}
+
+// 响应示例
+[
+  {
+    "id": 1936,
+    "title": "测试文档1",
+    "status": "active",
+    "ou_id": "yunfu002",
+    "user_id": 9,
+    "created_at": "2025-11-15T10:30:00Z"
+  },
+  {
+    "id": 1937,
+    "title": "测试文档2",
+    "status": "pending",
+    "ou_id": "yunfu002",
+    "user_id": 9,
+    "created_at": "2025-11-16T14:20:00Z"
+  }
+]
+```
+
+#### 3.2.2 分页查询
+
+PostgREST使用`limit`和`offset`参数实现分页。
+
+```javascript
+// 分页查询：每页10条，第2页
+async function getDocumentsPaginated(page = 1, pageSize = 10) {
+  const offset = (page - 1) * pageSize;
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      limit: pageSize,
+      offset: offset
+    }
+  });
+  return response.data;
+}
+
+// 使用示例
+const documents = await getDocumentsPaginated(2, 10); // 第2页，每页10条
+```
+
+#### 3.2.3 过滤查询
+
+PostgREST支持丰富的过滤运算符：
+
+| 运算符 | 说明 | 示例 |
+|--------|------|------|
+| `eq` | 等于 | `status=eq.active` |
+| `neq` | 不等于 | `status=neq.deleted` |
+| `gt` | 大于 | `created_at=gt.2025-01-01` |
+| `gte` | 大于等于 | `score=gte.80` |
+| `lt` | 小于 | `priority=lt.5` |
+| `lte` | 小于等于 | `age=lte.30` |
+| `like` | 模糊匹配 | `title=like.*测试*` |
+| `ilike` | 不区分大小写模糊匹配 | `title=ilike.*TEST*` |
+| `in` | 在列表中 | `status=in.(active,pending)` |
+| `is` | 是null | `deleted_at=is.null` |
+
+**示例**:
+```javascript
+// 查询状态为active的文档
+async function getActiveDocuments() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      status: 'eq.active'
+    }
+  });
+  return response.data;
+}
+
+// 查询标题包含"合同"的文档
+async function searchDocuments(keyword) {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      title: `ilike.*${keyword}*`
+    }
+  });
+  return response.data;
+}
+
+// 多条件查询：状态为active且创建时间在2025年之后
+async function getRecentActiveDocuments() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      status: 'eq.active',
+      created_at: 'gte.2025-01-01'
+    }
+  });
+  return response.data;
+}
+```
+
+#### 3.2.4 排序
+
+使用`order`参数指定排序字段和方向。
+
+```javascript
+// 按创建时间降序排列
+async function getDocumentsSorted() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      order: 'created_at.desc'
+    }
+  });
+  return response.data;
+}
+
+// 多字段排序：先按状态升序，再按创建时间降序
+async function getDocumentsMultiSort() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      order: 'status.asc,created_at.desc'
+    }
+  });
+  return response.data;
+}
+```
+
+#### 3.2.5 字段选择
+
+使用`select`参数指定返回的字段。
+
+```javascript
+// 只返回id、title、status字段
+async function getDocumentsPartial() {
+  const response = await apiClient.get('/postgrest/documents', {
+    params: {
+      select: 'id,title,status'
+    }
+  });
+  return response.data;
+}
+
+// 响应示例
+[
+  {
+    "id": 1936,
+    "title": "测试文档1",
+    "status": "active"
+  }
+]
+```
+
+### 3.3 创建操作 (POST)
+
+```javascript
+// 创建新文档
+async function createDocument(documentData) {
+  const response = await apiClient.post('/postgrest/documents', documentData);
+  return response.data;
+}
+
+// 使用示例
+const newDocument = await createDocument({
+  title: '新文档',
+  content: '文档内容',
+  status: 'draft',
+  ou_id: 'yunfu002',  // 后端会自动验证ou_id是否在用户权限范围内
+  user_id: 9
+});
+
+// 成功响应 (HTTP 201)
+[
+  {
+    "id": 2001,
+    "title": "新文档",
+    "content": "文档内容",
+    "status": "draft",
+    "ou_id": "yunfu002",
+    "user_id": 9,
+    "created_at": "2025-11-17T10:00:00Z"
+  }
+]
+```
+
+**重要提示**:
+- 创建文档时，后端会自动验证`ou_id`和`user_id`是否符合用户的数据范围权限
+- 如果尝试创建不在权限范围内的数据，会返回403 Forbidden
+
+### 3.4 更新操作 (PATCH)
+
+```javascript
+// 更新文档状态
+async function updateDocumentStatus(documentId, newStatus) {
+  const response = await apiClient.patch('/postgrest/documents',
+    { status: newStatus },
+    {
+      params: {
+        id: `eq.${documentId}`
+      }
+    }
+  );
+  return response.data;
+}
+
+// 使用示例
+const updated = await updateDocumentStatus(1936, 'reviewed');
+
+// 成功响应 (HTTP 200)
+[
+  {
+    "id": 1936,
+    "title": "测试文档1",
+    "status": "reviewed",
+    "updated_at": "2025-11-17T11:00:00Z"
+  }
+]
+```
+
+**重要提示**:
+- 更新操作会自动应用数据范围过滤，用户只能更新自己权限范围内的数据
+- 对于交叉评查文档，如果用户参与了该文档的交叉评查任务，即使文档不在常规数据范围内，也可以更新
+
+### 3.5 删除操作 (DELETE)
+
+```javascript
+// 删除文档
+async function deleteDocument(documentId) {
+  const response = await apiClient.delete('/postgrest/documents', {
+    params: {
+      id: `eq.${documentId}`
+    }
+  });
+  return response.status === 204; // 成功删除返回204 No Content
+}
+
+// 使用示例
+const deleted = await deleteDocument(1936);
+if (deleted) {
+  console.log('文档删除成功');
+}
+```
+
+### 3.6 完整示例：文档管理
+
+```javascript
+// document-service.js
+import apiClient from './axios-instance';
+
+class DocumentService {
+  // 查询文档列表
+  async getDocuments(filters = {}) {
+    const params = {
+      limit: filters.pageSize || 10,
+      offset: ((filters.page || 1) - 1) * (filters.pageSize || 10),
+      ...filters.where
+    };
+
+    if (filters.orderBy) {
+      params.order = filters.orderBy;
+    }
+
+    const response = await apiClient.get('/postgrest/documents', { params });
+    return response.data;
+  }
+
+  // 获取单个文档
+  async getDocumentById(id) {
+    const response = await apiClient.get('/postgrest/documents', {
+      params: { id: `eq.${id}` }
+    });
+    return response.data[0]; // PostgREST返回数组，取第一个
+  }
+
+  // 创建文档
+  async createDocument(data) {
+    const response = await apiClient.post('/postgrest/documents', data);
+    return response.data[0];
+  }
+
+  // 更新文档
+  async updateDocument(id, data) {
+    const response = await apiClient.patch(
+      '/postgrest/documents',
+      data,
+      { params: { id: `eq.${id}` } }
+    );
+    return response.data[0];
+  }
+
+  // 删除文档
+  async deleteDocument(id) {
+    await apiClient.delete('/postgrest/documents', {
+      params: { id: `eq.${id}` }
+    });
+    return true;
+  }
+}
+
+export default new DocumentService();
+```
+
+**使用示例**:
+```javascript
+import DocumentService from './document-service';
+
+// 1. 查询文档列表（分页、过滤、排序）
+const documents = await DocumentService.getDocuments({
+  page: 1,
+  pageSize: 10,
+  where: {
+    status: 'eq.active',
+    title: 'ilike.*合同*'
+  },
+  orderBy: 'created_at.desc'
+});
+
+// 2. 获取单个文档
+const document = await DocumentService.getDocumentById(1936);
+
+// 3. 创建文档
+const newDoc = await DocumentService.createDocument({
+  title: '采购合同',
+  content: '合同内容...',
+  status: 'draft'
+});
+
+// 4. 更新文档
+const updatedDoc = await DocumentService.updateDocument(1936, {
+  status: 'reviewed'
+});
+
+// 5. 删除文档
+await DocumentService.deleteDocument(1936);
+```
+
+---
+
+## 4. RBAC权限系统
+
+### 4.1 权限模型
+
+DocAuditAI采用**RBAC（基于角色的访问控制）**模型，支持：
+
+- **用户-角色关联**: 一个用户可以有多个角色
+- **角色-权限关联**: 一个角色可以有多个权限
+- **用户-权限关联**: 用户可以直接拥有权限（绕过角色）
+- **数据范围控制**: 细粒度的数据访问权限（ALL/DEPT/DEPT_AND_SUB/SELF/CUSTOM）
+
+#### 权限键格式
+
+权限键格式为：`{module}:{resource}:{action}`
+
+**示例**:
+- `document:document:view` - 查看文档
+- `document:document:create` - 创建文档
+- `document:document:update` - 更新文档
+- `document:document:delete` - 删除文档
+- `crossreview:task:view` - 查看交叉评查任务
+
+### 4.2 自动权限检查
+
+**所有通过PostgREST代理的请求都会自动进行权限检查**，前端无需手动调用权限检查接口。
+
+**权限检查流程**:
+1. 用户发起请求（携带JWT Token）
+2. 后端解析Token，提取用户ID和角色
+3. 根据表名和HTTP方法映射到权限键
+4. 检查用户是否拥有该权限
+5. 如果有权限，继续处理请求；否则返回403 Forbidden
+
+**示例**:
+```javascript
+// GET /api/v1/postgrest/documents
+// 后端自动检查权限: document:document:view
+
+// POST /api/v1/postgrest/documents
+// 后端自动检查权限: document:document:create
+
+// PATCH /api/v1/postgrest/documents?id=eq.1936
+// 后端自动检查权限: document:document:update
+
+// DELETE /api/v1/postgrest/documents?id=eq.1936
+// 后端自动检查权限: document:document:delete
+```
+
+### 4.3 前端权限控制
+
+虽然后端会自动检查权限，但前端也应该根据用户权限**隐藏或禁用**无权操作的按钮和菜单。
+
+#### 4.3.1 获取当前用户权限
+
+```javascript
+// 从Token中解析用户信息（包含角色）
+function getUserInfo() {
+  const userInfoStr = localStorage.getItem('user_info');
+  if (!userInfoStr) return null;
+  return JSON.parse(userInfoStr);
+}
+
+// 检查用户是否有特定角色
+function hasRole(roleName) {
+  const userInfo = getUserInfo();
+  return userInfo?.roles?.includes(roleName) || false;
+}
+
+// 使用示例
+if (hasRole('系统管理员')) {
+  // 显示管理员菜单
+}
+```
+
+#### 4.3.2 权限指令（Vue示例）
+
+```vue
+<!-- Vue自定义指令：v-permission -->
+<template>
+  <button v-permission="'document:document:delete'" @click="deleteDoc">
+    删除文档
+  </button>
+</template>
+
+<script>
+// permission-directive.js
+export default {
+  mounted(el, binding) {
+    const permission = binding.value;
+    const userInfo = JSON.parse(localStorage.getItem('user_info') || '{}');
+
+    // 简化版：根据角色判断（实际应该调用后端接口获取完整权限列表）
+    const hasPermission = checkPermission(userInfo, permission);
+
+    if (!hasPermission) {
+      el.style.display = 'none'; // 隐藏按钮
+      // 或者禁用按钮
+      // el.disabled = true;
+    }
+  }
+};
+
+function checkPermission(userInfo, permission) {
+  // 简化逻辑：管理员拥有所有权限
+  if (userInfo.roles?.includes('系统管理员')) return true;
+
+  // 实际应该维护一个角色-权限映射表或调用后端接口
+  const rolePermissions = {
+    '文档审查员': ['document:document:view', 'document:document:update'],
+    '文档管理员': ['document:document:view', 'document:document:create', 'document:document:update', 'document:document:delete']
+  };
+
+  return userInfo.roles?.some(role => rolePermissions[role]?.includes(permission)) || false;
+}
+</script>
+```
+
+**推荐做法**:
+1. 登录时从后端获取用户的完整权限列表（包括通过角色继承的权限和直接分配的权限）
+2. 将权限列表存储到Vuex/Pinia/Redux中
+3. 前端根据权限列表控制UI元素的显示/隐藏
+
+---
+
+## 5. 数据范围过滤
+
+### 5.1 数据范围类型
+
+DocAuditAI支持5种数据范围类型：
+
+| 数据范围 | 说明 | 过滤逻辑 |
+|---------|------|---------|
+| **ALL** | 全部数据 | 无过滤，可查看所有数据 |
+| **DEPT** | 本部门数据 | `ou_id = 用户的ou_id` |
+| **DEPT_AND_SUB** | 本部门及下级部门数据 | `ou_id IN (用户的ou_id_tree)` |
+| **SELF** | 本人数据 | `user_id = 用户ID` |
+| **CUSTOM** | 自定义规则 | 根据自定义SQL表达式过滤 |
+
+### 5.2 自动数据范围过滤
+
+**所有通过PostgREST代理的查询请求都会自动应用数据范围过滤**，前端无需关心过滤逻辑。
+
+**示例**:
+```javascript
+// 用户A（数据范围SELF，user_id=9）
+// 请求: GET /api/v1/postgrest/documents
+// 后端自动添加过滤: user_id=eq.9
+
+// 用户B（数据范围DEPT，ou_id=yunfu002）
+// 请求: GET /api/v1/postgrest/documents
+// 后端自动添加过滤: ou_id=eq.yunfu002
+
+// 用户C（数据范围ALL）
+// 请求: GET /api/v1/postgrest/documents
+// 后端无过滤，返回所有文档
+```
+
+### 5.3 前端注意事项
+
+1. **不要尝试绕过数据范围过滤**
+   后端会强制覆盖前端提供的`ou_id`或`user_id`参数，尝试绕过会被拒绝或忽略。
+
+   ```javascript
+   // ❌ 错误示例：尝试访问其他部门数据
+   const response = await apiClient.get('/postgrest/documents', {
+     params: {
+       ou_id: 'eq.guangzhou001' // 后端会覆盖为用户自己的ou_id
+     }
+   });
+
+   // ✅ 正确示例：正常查询，后端自动应用数据范围
+   const response = await apiClient.get('/postgrest/documents');
+   ```
+
+2. **数据范围对不同操作的影响**
+   - **查询（GET）**: 自动过滤，只返回权限范围内的数据
+   - **创建（POST）**: 验证ou_id/user_id是否在权限范围内
+   - **更新（PATCH）**: 只能更新权限范围内的数据
+   - **删除（DELETE）**: 只能删除权限范围内的数据
+
+---
+
+## 6. 交叉评查权限
+
+### 6.1 交叉评查权限概述
+
+交叉评查允许用户**跨部门访问**特定文档，即使这些文档不在其常规数据范围内。
+
+**应用场景**:
+- 用户A（云浮部门）参与了一个交叉评查任务，该任务包含来自梅州部门的文档
+- 用户A可以查看和评审这些梅州文档，尽管其常规数据范围是SELF（只能看自己的）
+
+### 6.2 交叉评查权限逻辑
+
+对于配置了`special_handling='cross_review_mixed'`的表（如`documents`），后端会：
+
+1. **GET请求**: 扩展访问范围（常规数据范围 **OR** 交叉评查文档）
+   ```
+   常规过滤: user_id=eq.9
+   交叉评查扩展: id.in.(1936,1937)
+   最终过滤: or=(id.in.(1936,1937),user_id.eq.9)
+   ```
+
+2. **PATCH/DELETE请求**: 检查目标文档是否在交叉评查范围
+   - 如果是交叉评查文档 → 移除常规数据范围限制，允许操作
+   - 如果不是 → 保持常规数据范围限制
+
+### 6.3 前端使用示例
+
+前端无需特殊处理，后端会自动处理交叉评查权限。
+
+```javascript
+// 场景：用户9（数据范围SELF）参与了任务183的交叉评查
+// 任务183包含文档[1936, 1937]（来自其他用户）
+
+// 1. 查询文档列表
+const documents = await apiClient.get('/postgrest/documents');
+// 返回：
+// - 用户自己的文档（user_id=9）
+// - 交叉评查文档[1936, 1937]
+
+// 2. 更新交叉评查文档
+const updated = await apiClient.patch(
+  '/postgrest/documents',
+  { status: 'reviewed' },
+  { params: { id: 'eq.1936' } }
+);
+// 成功：后端检测到1936是交叉评查文档，允许更新
+
+// 3. 尝试更新其他用户的非交叉评查文档
+try {
+  await apiClient.patch(
+    '/postgrest/documents',
+    { status: 'reviewed' },
+    { params: { id: 'eq.9999' } } // 不在交叉评查范围
+  );
+} catch (error) {
+  console.error('无权更新此文档'); // 403 Forbidden
+}
+```
+
+### 6.4 获取交叉评查任务
+
+```javascript
+// 查询当前用户的交叉评查任务
+async function getCrossReviewTasks() {
+  const response = await apiClient.get('/postgrest/cross_examination_tasks');
+  return response.data;
+}
+
+// 响应示例
+[
+  {
+    "id": 183,
+    "task_name": "2025年第一季度交叉评查",
+    "status": "in_progress",
+    "created_by": 5,
+    "user_ids": [9, 10, 11], // 参与用户
+    "created_at": "2025-11-10T09:00:00Z"
+  }
+]
+```
+
+---
+
+## 7. 错误处理
+
+### 7.1 HTTP状态码
+
+| 状态码 | 说明 | 处理建议 |
+|--------|------|---------|
+| **200 OK** | 请求成功 | 正常处理数据 |
+| **201 Created** | 创建成功 | 显示成功消息 |
+| **204 No Content** | 删除成功 | 显示成功消息 |
+| **400 Bad Request** | 请求参数错误 | 检查请求参数格式 |
+| **401 Unauthorized** | 未认证或Token无效 | 跳转到登录页 |
+| **403 Forbidden** | 无权限 | 显示"无权限"提示 |
+| **404 Not Found** | 资源不存在 | 显示"资源不存在"提示 |
+| **500 Internal Server Error** | 服务器错误 | 显示"服务器错误"提示 |
+
+### 7.2 错误响应格式
+
+**标准错误响应**:
+```json
+{
+  "detail": "错误描述"
+}
+```
+
+**详细错误响应**（包含更多上下文）:
+```json
+{
+  "detail": "权限不足",
+  "error_code": "PERMISSION_DENIED",
+  "permission_required": "document:document:delete",
+  "user_id": 9
+}
+```
+
+### 7.3 全局错误处理
+
+```javascript
+// axios-instance.js
+apiClient.interceptors.response.use(
+  response => response,
+  error => {
+    const status = error.response?.status;
+    const detail = error.response?.data?.detail || '未知错误';
+
+    switch (status) {
+      case 400:
+        // 请求参数错误
+        console.error('请求参数错误:', detail);
+        alert(`请求参数错误: ${detail}`);
+        break;
+
+      case 401:
+        // 未认证或Token无效
+        console.error('认证失败，跳转到登录页');
+        localStorage.removeItem('access_token');
+        localStorage.removeItem('user_info');
+        window.location.href = '/login';
+        break;
+
+      case 403:
+        // 无权限
+        console.error('权限不足:', detail);
+        alert(`权限不足: ${detail}`);
+        break;
+
+      case 404:
+        // 资源不存在
+        console.error('资源不存在:', detail);
+        alert(`资源不存在: ${detail}`);
+        break;
+
+      case 500:
+        // 服务器错误
+        console.error('服务器错误:', detail);
+        alert(`服务器错误，请稍后重试`);
+        break;
+
+      default:
+        console.error('未知错误:', error);
+        alert(`请求失败，请稍后重试`);
+    }
+
+    return Promise.reject(error);
+  }
+);
+```
+
+### 7.4 特定错误处理
+
+```javascript
+// 创建文档时处理权限错误
+async function createDocumentWithErrorHandling(data) {
+  try {
+    const response = await apiClient.post('/postgrest/documents', data);
+    alert('文档创建成功');
+    return response.data[0];
+  } catch (error) {
+    if (error.response?.status === 403) {
+      const detail = error.response.data?.detail || '权限不足';
+      if (detail.includes('数据范围')) {
+        alert('您无权在此组织单位创建文档');
+      } else {
+        alert('您没有创建文档的权限');
+      }
+    } else {
+      alert('创建文档失败，请重试');
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## 8. 常用示例
+
+### 8.1 文档列表页面
+
+```vue
+<template>
+  <div class="document-list">
+    <h1>文档列表</h1>
+
+    <!-- 搜索框 -->
+    <div class="search-bar">
+      <input
+        v-model="searchKeyword"
+        @input="onSearch"
+        placeholder="搜索文档标题"
+      />
+      <select v-model="searchStatus" @change="onSearch">
+        <option value="">全部状态</option>
+        <option value="draft">草稿</option>
+        <option value="active">活跃</option>
+        <option value="reviewed">已评查</option>
+      </select>
+    </div>
+
+    <!-- 文档列表 -->
+    <table>
+      <thead>
+        <tr>
+          <th>ID</th>
+          <th>标题</th>
+          <th>状态</th>
+          <th>创建时间</th>
+          <th>操作</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="doc in documents" :key="doc.id">
+          <td>{{ doc.id }}</td>
+          <td>{{ doc.title }}</td>
+          <td>{{ doc.status }}</td>
+          <td>{{ formatDate(doc.created_at) }}</td>
+          <td>
+            <button @click="viewDocument(doc.id)">查看</button>
+            <button
+              v-permission="'document:document:update'"
+              @click="editDocument(doc.id)"
+            >
+              编辑
+            </button>
+            <button
+              v-permission="'document:document:delete'"
+              @click="deleteDocument(doc.id)"
+            >
+              删除
+            </button>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+
+    <!-- 分页 -->
+    <div class="pagination">
+      <button @click="prevPage" :disabled="currentPage === 1">上一页</button>
+      <span>第 {{ currentPage }} 页 / 共 {{ totalPages }} 页</span>
+      <button @click="nextPage" :disabled="currentPage === totalPages">下一页</button>
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref, onMounted } from 'vue';
+import apiClient from '@/services/axios-instance';
+
+export default {
+  setup() {
+    const documents = ref([]);
+    const currentPage = ref(1);
+    const pageSize = ref(10);
+    const totalPages = ref(1);
+    const searchKeyword = ref('');
+    const searchStatus = ref('');
+
+    // 加载文档列表
+    async function loadDocuments() {
+      try {
+        const params = {
+          limit: pageSize.value,
+          offset: (currentPage.value - 1) * pageSize.value,
+          order: 'created_at.desc'
+        };
+
+        if (searchKeyword.value) {
+          params.title = `ilike.*${searchKeyword.value}*`;
+        }
+
+        if (searchStatus.value) {
+          params.status = `eq.${searchStatus.value}`;
+        }
+
+        const response = await apiClient.get('/postgrest/documents', { params });
+        documents.value = response.data;
+
+        // 计算总页数（PostgREST返回Content-Range头）
+        const contentRange = response.headers['content-range'];
+        if (contentRange) {
+          const total = parseInt(contentRange.split('/')[1]);
+          totalPages.value = Math.ceil(total / pageSize.value);
+        }
+      } catch (error) {
+        console.error('加载文档失败:', error);
+      }
+    }
+
+    // 搜索
+    function onSearch() {
+      currentPage.value = 1;
+      loadDocuments();
+    }
+
+    // 分页
+    function prevPage() {
+      if (currentPage.value > 1) {
+        currentPage.value--;
+        loadDocuments();
+      }
+    }
+
+    function nextPage() {
+      if (currentPage.value < totalPages.value) {
+        currentPage.value++;
+        loadDocuments();
+      }
+    }
+
+    // 删除文档
+    async function deleteDocument(id) {
+      if (!confirm('确定要删除此文档吗？')) return;
+
+      try {
+        await apiClient.delete('/postgrest/documents', {
+          params: { id: `eq.${id}` }
+        });
+        alert('删除成功');
+        loadDocuments();
+      } catch (error) {
+        console.error('删除失败:', error);
+      }
+    }
+
+    // 格式化日期
+    function formatDate(dateStr) {
+      return new Date(dateStr).toLocaleString('zh-CN');
+    }
+
+    onMounted(() => {
+      loadDocuments();
+    });
+
+    return {
+      documents,
+      currentPage,
+      totalPages,
+      searchKeyword,
+      searchStatus,
+      onSearch,
+      prevPage,
+      nextPage,
+      deleteDocument,
+      formatDate
+    };
+  }
+};
+</script>
+```
+
+### 8.2 文档详情页面
+
+```vue
+<template>
+  <div class="document-detail">
+    <h1>{{ document.title }}</h1>
+
+    <div class="meta">
+      <p>状态: {{ document.status }}</p>
+      <p>创建时间: {{ formatDate(document.created_at) }}</p>
+      <p>更新时间: {{ formatDate(document.updated_at) }}</p>
+    </div>
+
+    <div class="content">
+      {{ document.content }}
+    </div>
+
+    <div class="actions">
+      <button
+        v-permission="'document:document:update'"
+        @click="editDocument"
+      >
+        编辑
+      </button>
+      <button
+        v-permission="'document:document:update'"
+        @click="changeStatus('reviewed')"
+      >
+        标记为已评查
+      </button>
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref, onMounted } from 'vue';
+import { useRoute } from 'vue-router';
+import apiClient from '@/services/axios-instance';
+
+export default {
+  setup() {
+    const route = useRoute();
+    const document = ref({});
+
+    // 加载文档详情
+    async function loadDocument() {
+      try {
+        const id = route.params.id;
+        const response = await apiClient.get('/postgrest/documents', {
+          params: { id: `eq.${id}` }
+        });
+        document.value = response.data[0];
+      } catch (error) {
+        console.error('加载文档失败:', error);
+        alert('加载文档失败');
+      }
+    }
+
+    // 更改状态
+    async function changeStatus(newStatus) {
+      try {
+        await apiClient.patch(
+          '/postgrest/documents',
+          { status: newStatus },
+          { params: { id: `eq.${document.value.id}` } }
+        );
+        alert('状态更新成功');
+        loadDocument();
+      } catch (error) {
+        console.error('更新状态失败:', error);
+      }
+    }
+
+    function formatDate(dateStr) {
+      return new Date(dateStr).toLocaleString('zh-CN');
+    }
+
+    onMounted(() => {
+      loadDocument();
+    });
+
+    return {
+      document,
+      changeStatus,
+      formatDate
+    };
+  }
+};
+</script>
+```
+
+---
+
+## 9. 最佳实践
+
+### 9.1 安全最佳实践
+
+1. **始终使用HTTPS**
+   生产环境必须使用HTTPS传输，防止Token被窃取。
+
+2. **安全存储Token**
+   - 使用`localStorage`或`sessionStorage`存储Token
+   - 不要将Token存储在Cookie中（避免CSRF攻击）
+   - 不要将Token暴露在URL参数中
+
+3. **Token过期处理**
+   - 定期检查Token是否过期
+   - Token过期后立即跳转到登录页
+   - 提供Token刷新机制（如果后端支持）
+
+4. **不要绕过前端权限检查**
+   - 即使前端隐藏了按钮，用户仍可能通过开发者工具发起请求
+   - 后端会强制执行权限检查，前端绕过无效
+
+### 9.2 性能最佳实践
+
+1. **分页查询**
+   始终使用分页，避免一次性加载大量数据。
+
+   ```javascript
+   // ✅ 好的做法
+   const response = await apiClient.get('/postgrest/documents', {
+     params: { limit: 10, offset: 0 }
+   });
+
+   // ❌ 不好的做法
+   const response = await apiClient.get('/postgrest/documents'); // 返回所有数据
+   ```
+
+2. **字段选择**
+   只查询需要的字段，减少数据传输量。
+
+   ```javascript
+   // ✅ 好的做法
+   const response = await apiClient.get('/postgrest/documents', {
+     params: { select: 'id,title,status' }
+   });
+
+   // ❌ 不好的做法
+   const response = await apiClient.get('/postgrest/documents'); // 返回所有字段
+   ```
+
+3. **缓存数据**
+   对于不经常变化的数据（如字典表、配置表），使用前端缓存。
+
+   ```javascript
+   // 缓存字典数据
+   let documentTypesCache = null;
+
+   async function getDocumentTypes() {
+     if (documentTypesCache) {
+       return documentTypesCache;
+     }
+
+     const response = await apiClient.get('/postgrest/document_types');
+     documentTypesCache = response.data;
+
+     // 5分钟后过期
+     setTimeout(() => {
+       documentTypesCache = null;
+     }, 5 * 60 * 1000);
+
+     return documentTypesCache;
+   }
+   ```
+
+4. **批量操作**
+   尽量减少请求次数，使用批量操作。
+
+   ```javascript
+   // ❌ 不好的做法：逐个删除
+   for (const id of [1, 2, 3]) {
+     await apiClient.delete('/postgrest/documents', {
+       params: { id: `eq.${id}` }
+     });
+   }
+
+   // ✅ 好的做法：批量删除
+   await apiClient.delete('/postgrest/documents', {
+     params: { id: `in.(1,2,3)` }
+   });
+   ```
+
+### 9.3 用户体验最佳实践
+
+1. **加载状态**
+   显示加载指示器，提升用户体验。
+
+   ```vue
+   <template>
+     <div v-if="loading">加载中...</div>
+     <div v-else>
+       <!-- 内容 -->
+     </div>
+   </template>
+
+   <script>
+   export default {
+     data() {
+       return {
+         loading: false
+       };
+     },
+     methods: {
+       async loadData() {
+         this.loading = true;
+         try {
+           // 加载数据
+         } finally {
+           this.loading = false;
+         }
+       }
+     }
+   };
+   </script>
+   ```
+
+2. **错误提示**
+   友好的错误提示，避免显示技术细节。
+
+   ```javascript
+   // ❌ 不好的做法
+   alert(error.message); // "Cannot read property 'data' of undefined"
+
+   // ✅ 好的做法
+   alert('加载数据失败，请稍后重试');
+   ```
+
+3. **操作确认**
+   对于删除等危险操作，提供确认提示。
+
+   ```javascript
+   async function deleteDocument(id) {
+     if (!confirm('确定要删除此文档吗？此操作不可撤销。')) {
+       return;
+     }
+
+     try {
+       await apiClient.delete('/postgrest/documents', {
+         params: { id: `eq.${id}` }
+       });
+       alert('删除成功');
+     } catch (error) {
+       alert('删除失败');
+     }
+   }
+   ```
+
+---
+
+## 10. 故障排查
+
+### 10.1 常见问题
+
+#### 问题1：401 Unauthorized - Token无效
+
+**症状**: 所有API请求返回401错误。
+
+**原因**:
+- Token已过期
+- Token格式错误
+- Token未正确携带在请求头中
+
+**解决方法**:
+1. 检查Token是否存在：`localStorage.getItem('access_token')`
+2. 检查Token格式是否正确（应为`Bearer {token}`）
+3. 检查Token是否过期
+4. 重新登录获取新Token
+
+#### 问题2：403 Forbidden - 权限不足
+
+**症状**: 某些API请求返回403错误。
+
+**原因**:
+- 用户没有该操作的权限
+- 尝试访问不在数据范围内的数据
+
+**解决方法**:
+1. 确认用户是否有对应的权限（检查用户角色）
+2. 确认数据是否在用户的数据范围内
+3. 联系管理员分配权限
+
+#### 问题3：CORS错误
+
+**症状**: 浏览器控制台显示CORS错误。
+
+**原因**:
+- 前端域名未在后端CORS白名单中
+
+**解决方法**:
+1. 联系后端开发人员将前端域名添加到CORS白名单
+2. 开发环境可以配置代理绕过CORS
+
+**Vue.js开发环境代理配置**:
+```javascript
+// vue.config.js
+module.exports = {
+  devServer: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8000',
+        changeOrigin: true
+      }
+    }
+  }
+};
+```
+
+#### 问题4：数据未按预期过滤
+
+**症状**: 查询返回了不应该看到的数据。
+
+**原因**:
+- 后端数据范围配置错误
+- 前端缓存了旧数据
+
+**解决方法**:
+1. 清除浏览器缓存和localStorage
+2. 检查用户的数据范围配置是否正确
+3. 联系后端开发人员检查RBAC配置
+
+### 10.2 调试技巧
+
+#### 1. 查看请求详情
+
+使用浏览器开发者工具查看请求详情：
+1. 打开开发者工具（F12）
+2. 切换到Network标签
+3. 发起请求
+4. 点击请求查看Headers、Payload、Response
+
+#### 2. 查看Token内容
+
+```javascript
+// 解码JWT Token
+function decodeToken(token) {
+  try {
+    const payload = JSON.parse(atob(token.split('.')[1]));
+    console.log('Token内容:', payload);
+    return payload;
+  } catch (e) {
+    console.error('Token解码失败:', e);
+    return null;
+  }
+}
+
+// 使用示例
+const token = localStorage.getItem('access_token');
+decodeToken(token);
+```
+
+#### 3. 启用详细日志
+
+```javascript
+// axios-instance.js
+apiClient.interceptors.request.use(config => {
+  console.log('[Request]', config.method.toUpperCase(), config.url, config.params);
+  return config;
+});
+
+apiClient.interceptors.response.use(
+  response => {
+    console.log('[Response]', response.status, response.data);
+    return response;
+  },
+  error => {
+    console.error('[Error]', error.response?.status, error.response?.data);
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## 附录
+
+### A. 完整API端点列表
+
+详见：[API端点列表文档](./前端对接文档-API端点列表.md)
+
+### B. PostgREST过滤运算符完整列表
+
+详见：[PostgREST查询参考](./前端对接文档-PostgREST查询参考.md)
+
+### C. 权限列表
+
+详见：[权限列表文档](./前端对接文档-权限列表.md)
+
+---
+
+## 联系支持
+
+如有问题或建议，请联系：
+- **技术支持**: support@docauditai.com
+- **开发团队**: dev@docauditai.com
+
+---
+
+**文档版本**: v1.0
+**最后更新**: 2025-11-17
+**维护者**: Claude Code
diff --git a/auth_doc/前端快速开始_5分钟集成.md b/auth_doc/前端快速开始_5分钟集成.md
new file mode 100644
index 0000000..0205862
--- /dev/null
+++ b/auth_doc/前端快速开始_5分钟集成.md
@@ -0,0 +1,333 @@
+# 前端快速开始 - 5分钟集成RBAC系统
+
+**版本**: v1.0
+**日期**: 2025-11-17
+**目标**: 最快速度集成登录、动态路由和数据访问
+
+---
+
+## ⚡ 5分钟集成步骤
+
+### 步骤1: 安装依赖（1分钟）
+
+```bash
+npm install axios pinia vue-router@4 element-plus
+```
+
+### 步骤2: 配置环境变量（30秒）
+
+创建 `.env.development`：
+
+```env
+VITE_API_BASE_URL=http://172.16.0.55:8073
+```
+
+### 步骤3: 创建请求工具（1分钟）
+
+**文件**: `src/utils/request.ts`
+
+```typescript
+import axios from 'axios';
+import { ElMessage } from 'element-plus';
+
+const service = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL || 'http://172.16.0.55:8073',
+  timeout: 30000
+});
+
+// 请求拦截器：自动添加Token
+service.interceptors.request.use(config => {
+  const token = localStorage.getItem('token');
+  if (token) {
+    config.headers['Authorization'] = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// 响应拦截器：统一错误处理
+service.interceptors.response.use(
+  response => response,
+  error => {
+    if (error.response?.status === 401) {
+      ElMessage.error('登录已过期');
+      localStorage.clear();
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+
+export default service;
+```
+
+### 步骤4: 创建用户Store（2分钟）
+
+**文件**: `src/stores/user.ts`
+
+```typescript
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+import request from '@/utils/request';
+import router from '@/router';
+
+export const useUserStore = defineStore('user', () => {
+  const token = ref('');
+  const userInfo = ref<any>(null);
+  const routes = ref<any[]>([]);
+
+  // 登录
+  const login = async (username: string, password: string) => {
+    const res = await request.post('/auth/login', { username, password });
+
+    if (res.data.success) {
+      token.value = res.data.data.access_token;
+      userInfo.value = res.data.data.user_info;
+
+      localStorage.setItem('token', token.value);
+      localStorage.setItem('userInfo', JSON.stringify(userInfo.value));
+
+      return true;
+    }
+    return false;
+  };
+
+  // 获取路由
+  const fetchRoutes = async () => {
+    const res = await request.get('/user/routes');
+
+    if (res.data.code === 200) {
+      routes.value = res.data.data.routes;
+
+      // 动态注册路由
+      routes.value.forEach(route => {
+        router.addRoute({
+          path: route.route_path,
+          name: route.route_name,
+          component: () => import(`@/views/${route.component}.vue`),
+          meta: { title: route.route_title }
+        });
+      });
+
+      return routes.value;
+    }
+  };
+
+  // 登出
+  const logout = () => {
+    token.value = '';
+    userInfo.value = null;
+    routes.value = [];
+    localStorage.clear();
+    router.push('/login');
+  };
+
+  return { token, userInfo, routes, login, fetchRoutes, logout };
+});
+```
+
+### 步骤5: 配置路由守卫（30秒）
+
+**文件**: `src/router/index.ts`
+
+```typescript
+import { createRouter, createWebHistory } from 'vue-router';
+import { useUserStore } from '@/stores/user';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/login', component: () => import('@/views/Login.vue') }
+  ]
+});
+
+router.beforeEach(async (to, from, next) => {
+  const userStore = useUserStore();
+  const token = localStorage.getItem('token');
+
+  if (token && !userStore.token) {
+    userStore.token = token;
+    userStore.userInfo = JSON.parse(localStorage.getItem('userInfo') || '{}');
+  }
+
+  if (to.path !== '/login' && !token) {
+    next('/login');
+  } else if (token && !userStore.routes.length) {
+    await userStore.fetchRoutes();
+    next({ ...to, replace: true });
+  } else {
+    next();
+  }
+});
+
+export default router;
+```
+
+### 步骤6: 创建登录页（30秒）
+
+**文件**: `src/views/Login.vue`
+
+```vue
+<template>
+  <el-form @submit.prevent="handleLogin">
+    <el-form-item>
+      <el-input v-model="username" placeholder="用户名" />
+    </el-form-item>
+    <el-form-item>
+      <el-input v-model="password" type="password" placeholder="密码" />
+    </el-form-item>
+    <el-form-item>
+      <el-button type="primary" native-type="submit" :loading="loading">
+        登录
+      </el-button>
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { useUserStore } from '@/stores/user';
+import { ElMessage } from 'element-plus';
+
+const router = useRouter();
+const userStore = useUserStore();
+
+const username = ref('');
+const password = ref('');
+const loading = ref(false);
+
+const handleLogin = async () => {
+  loading.value = true;
+
+  try {
+    const success = await userStore.login(username.value, password.value);
+
+    if (success) {
+      await userStore.fetchRoutes();
+      router.push('/home');
+    } else {
+      ElMessage.error('登录失败');
+    }
+  } catch (error) {
+    ElMessage.error('登录失败');
+  } finally {
+    loading.value = false;
+  }
+};
+</script>
+```
+
+---
+
+## ✅ 完成！
+
+现在你已经完成了基础集成，可以：
+
+1. ✅ 用户登录
+2. ✅ 动态加载路由
+3. ✅ 访问受保护的页面
+
+---
+
+## 🚀 下一步：数据访问
+
+### 查询数据
+
+```typescript
+import request from '@/utils/request';
+
+// 查询文档列表
+const fetchDocuments = async () => {
+  const res = await request.get('/documents', {
+    params: {
+      user_id: `eq.${userInfo.user_id}`,  // 只查自己的数据
+      limit: 20,
+      offset: 0
+    }
+  });
+  return res.data;
+};
+```
+
+### 创建数据
+
+```typescript
+const createDocument = async (data: any) => {
+  const res = await request.post('/documents', data);
+  return res.data;
+};
+```
+
+### 更新数据
+
+```typescript
+const updateDocument = async (id: number, data: any) => {
+  const res = await request.patch(`/documents?id=eq.${id}`, data);
+  return res.data;
+};
+```
+
+### 删除数据
+
+```typescript
+const deleteDocument = async (id: number) => {
+  const res = await request.delete(`/documents?id=eq.${id}`);
+  return res.data;
+};
+```
+
+---
+
+## 📚 测试账号
+
+| 用户名 | 密码 | 角色 | 说明 |
+|--------|------|------|------|
+| 000 | admin06111 | 超级管理员 | 所有权限（29个路由） |
+| 001 | gdyc06111 | 普通用户 | 有限权限（19个路由） |
+| jy001 | jyyc0814 | 系统管理员 | 所有权限（29个路由） |
+
+---
+
+## 🔧 常见问题
+
+### 1. Token过期怎么办？
+
+后端返回401时，自动清除Token并跳转登录页。
+
+### 2. 路由404怎么办？
+
+检查组件路径是否正确：
+
+```typescript
+// 后端返回: component: "views/Home"
+// 前端import: @/views/views/Home.vue ❌
+
+// 修改为:
+component: () => import(`@/views/Home.vue`)
+```
+
+### 3. 普通用户能看到所有数据？
+
+前端必须手动添加 `user_id` 过滤：
+
+```typescript
+// ❌ 错误
+const docs = await request.get('/documents');
+
+// ✅ 正确
+const docs = await request.get('/documents', {
+  params: { user_id: `eq.${userInfo.user_id}` }
+});
+```
+
+---
+
+## 📖 详细文档
+
+完整API说明请查看：
+- **完整对接文档**: `docs/RBAC/前端完整对接文档_RBAC与PostgREST.md`
+
+---
+
+**创建时间**: 2025-11-17
+**维护者**: Claude Code
diff --git a/auth_doc/角色-路由权限实现方案.md b/auth_doc/角色-路由权限实现方案.md
new file mode 100644
index 0000000..3df0859
--- /dev/null
+++ b/auth_doc/角色-路由权限实现方案.md
@@ -0,0 +1,1180 @@
+# 角色-路由权限实现方案
+
+**版本**: v1.0
+**日期**: 2025-11-17
+**状态**: 设计完成，待实现
+
+---
+
+## 目录
+
+1. [功能概述](#功能概述)
+2. [设计原则](#设计原则)
+3. [架构设计](#架构设计)
+4. [数据库设计](#数据库设计)
+5. [后端实现](#后端实现)
+6. [前端实现](#前端实现)
+7. [安全策略](#安全策略)
+8. [性能优化](#性能优化)
+9. [实施步骤](#实施步骤)
+10. [测试方案](#测试方案)
+
+---
+
+## 功能概述
+
+### 业务需求
+
+实现**基于角色的前端路由权限控制**，使不同角色的用户登录后看到不同的菜单和页面：
+
+- ✅ **系统管理员** - 可访问所有路由（用户管理、角色管理、权限管理等）
+- ✅ **文档管理员** - 可访问文档管理相关路由
+- ✅ **文档审查员** - 可访问文档查看和评查路由
+- ✅ **普通用户** - 仅可访问基础路由（首页、个人中心）
+
+### 核心功能
+
+1. **路由定义管理** - 系统路由的增删改查
+2. **角色-路由关联** - 配置角色可访问的路由
+3. **用户路由查询** - 根据用户角色获取可访问路由列表
+4. **动态菜单生成** - 前端根据路由列表动态生成菜单
+5. **路由守卫** - 前端路由守卫拦截未授权访问
+
+---
+
+## 设计原则
+
+### 1. 高可用性原则
+
+- **缓存优先**: 路由权限数据缓存到 Redis（TTL: 30分钟）
+- **降级策略**: Redis 不可用时直接查询数据库
+- **异步刷新**: 后台定时刷新缓存，避免缓存雪崩
+
+### 2. 高性能原则
+
+- **单次查询**: 用户登录时一次性获取所有可访问路由
+- **前端缓存**: 路由数据存储在前端 LocalStorage
+- **懒加载**: 路由组件按需加载
+
+### 3. 安全性原则
+
+- **前后端双重验证**: 前端路由守卫 + 后端 API 权限校验
+- **最小权限**: 默认拒绝所有访问，显式授权
+- **审计日志**: 记录路由访问日志
+
+### 4. 可维护性原则
+
+- **配置化**: 路由通过数据库配置，无需修改代码
+- **层级结构**: 支持多级路由嵌套
+- **元信息**: 路由携带图标、标题等元信息
+
+---
+
+## 架构设计
+
+### 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        前端应用                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │ 路由守卫      │  │ 动态菜单      │  │ 权限指令      │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+                            ↓ HTTP请求
+┌─────────────────────────────────────────────────────────────┐
+│                      FastAPI 后端                            │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │ 路由权限API  │  │ 路由管理API  │  │ 角色管理API  │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+│  ┌──────────────────────────────────────────────────┐     │
+│  │          RoutePermission 模块                     │     │
+│  │  - get_user_routes()  获取用户可访问路由         │     │
+│  │  - get_role_routes()  获取角色可访问路由         │     │
+│  │  - check_route_access() 检查路由访问权限         │     │
+│  └──────────────────────────────────────────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│                      数据层                                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │ sys_routes   │  │ role_route   │  │ Redis Cache  │     │
+│  │ (路由定义)    │  │ (角色-路由)   │  │ (路由缓存)    │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 数据流向
+
+#### 用户登录流程
+
+```
+1. 用户登录
+   ↓
+2. 后端验证凭据
+   ↓
+3. 查询用户角色
+   ↓
+4. 根据角色查询可访问路由（优先从 Redis 缓存读取）
+   ↓
+5. 返回用户信息 + 路由列表
+   ↓
+6. 前端存储路由数据到 LocalStorage
+   ↓
+7. Vue Router 动态注册路由
+   ↓
+8. 根据路由生成侧边栏菜单
+```
+
+#### 路由访问流程
+
+```
+1. 用户访问路由（如 /system/users）
+   ↓
+2. 前端路由守卫拦截
+   ↓
+3. 检查路由是否在可访问列表
+   ↓
+4. [是] 允许访问 → 加载页面组件
+   ↓
+5. [否] 拒绝访问 → 跳转 403 页面
+```
+
+---
+
+## 数据库设计
+
+### 表结构
+
+#### 1. sys_routes（系统路由表）
+
+已存在，需要确认字段：
+
+```sql
+CREATE TABLE IF NOT EXISTS sys_routes (
+    id SERIAL PRIMARY KEY,
+    route_path VARCHAR(255) NOT NULL,           -- 路由路径 /system/users
+    route_name VARCHAR(100) NOT NULL,           -- 路由名称 UserManagement
+    component VARCHAR(255),                     -- 组件路径 views/system/Users.vue
+    parent_id INTEGER,                          -- 父路由ID（支持多级路由）
+    route_title VARCHAR(100),                   -- 路由标题（中文）
+    icon VARCHAR(50),                           -- 图标名称
+    sort_order INTEGER DEFAULT 0,               -- 排序顺序
+    is_hidden BOOLEAN DEFAULT FALSE,            -- 是否隐藏（隐藏的路由不显示在菜单）
+    is_cache BOOLEAN DEFAULT TRUE,              -- 是否缓存（KeepAlive）
+    meta JSONB,                                 -- 元信息（扩展字段）
+    status INTEGER DEFAULT 0,                   -- 状态 0=启用 1=禁用
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMP,
+
+    CONSTRAINT fk_parent_route FOREIGN KEY (parent_id) REFERENCES sys_routes(id) ON DELETE CASCADE
+);
+
+-- 索引
+CREATE INDEX idx_routes_parent_id ON sys_routes(parent_id);
+CREATE INDEX idx_routes_status ON sys_routes(status);
+CREATE UNIQUE INDEX idx_routes_path ON sys_routes(route_path) WHERE deleted_at IS NULL;
+```
+
+**字段说明**：
+- `route_path`: 前端路由路径，如 `/system/users`
+- `route_name`: 路由名称（唯一标识），如 `UserManagement`
+- `component`: 组件路径，如 `views/system/Users.vue`
+- `parent_id`: 父路由ID，支持多级嵌套菜单
+- `route_title`: 菜单显示的标题（中文）
+- `icon`: 图标（Element Plus / Ant Design 图标名）
+- `is_hidden`: 是否在菜单中隐藏（某些路由不显示在菜单，但可访问）
+- `meta`: JSON 扩展字段，存储额外信息（如权限标识、面包屑等）
+
+#### 2. role_route（角色-路由关联表）
+
+已存在，需要确认字段：
+
+```sql
+CREATE TABLE IF NOT EXISTS role_route (
+    id SERIAL PRIMARY KEY,
+    role_id INTEGER NOT NULL,
+    route_id INTEGER NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT fk_role FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
+    CONSTRAINT fk_route FOREIGN KEY (route_id) REFERENCES sys_routes(id) ON DELETE CASCADE,
+    CONSTRAINT uk_role_route UNIQUE (role_id, route_id)
+);
+
+-- 索引
+CREATE INDEX idx_role_route_role_id ON role_route(role_id);
+CREATE INDEX idx_role_route_route_id ON role_route(route_id);
+```
+
+### 数据示例
+
+#### 系统路由数据
+
+```sql
+-- 一级路由：首页
+INSERT INTO sys_routes (id, route_path, route_name, component, route_title, icon, sort_order)
+VALUES (1, '/dashboard', 'Dashboard', 'views/Dashboard.vue', '首页', 'el-icon-house', 1);
+
+-- 一级路由：系统管理（父菜单）
+INSERT INTO sys_routes (id, route_path, route_name, component, route_title, icon, sort_order)
+VALUES (2, '/system', 'System', 'Layout', '系统管理', 'el-icon-setting', 10);
+
+-- 二级路由：用户管理
+INSERT INTO sys_routes (id, route_path, route_name, component, parent_id, route_title, icon, sort_order)
+VALUES (3, '/system/users', 'SystemUsers', 'views/system/Users.vue', 2, '用户管理', 'el-icon-user', 1);
+
+-- 二级路由：角色管理
+INSERT INTO sys_routes (id, route_path, route_name, component, parent_id, route_title, icon, sort_order)
+VALUES (4, '/system/roles', 'SystemRoles', 'views/system/Roles.vue', 2, '角色管理', 'el-icon-user-filled', 2);
+
+-- 一级路由：文档管理
+INSERT INTO sys_routes (id, route_path, route_name, component, route_title, icon, sort_order)
+VALUES (10, '/documents', 'Documents', 'Layout', '文档管理', 'el-icon-document', 20);
+
+-- 二级路由：文档列表
+INSERT INTO sys_routes (id, route_path, route_name, component, parent_id, route_title, icon, sort_order)
+VALUES (11, '/documents/list', 'DocumentList', 'views/documents/List.vue', 10, '文档列表', 'el-icon-tickets', 1);
+```
+
+#### 角色-路由关联数据
+
+```sql
+-- 系统管理员 - 拥有所有路由
+INSERT INTO role_route (role_id, route_id)
+SELECT 1, id FROM sys_routes WHERE deleted_at IS NULL;
+
+-- 文档管理员 - 拥有首页 + 文档管理路由
+INSERT INTO role_route (role_id, route_id)
+VALUES (2, 1), (2, 10), (2, 11);
+
+-- 普通用户 - 只有首页
+INSERT INTO role_route (role_id, route_id)
+VALUES (8, 1);
+```
+
+---
+
+## 后端实现
+
+### 文件结构
+
+```
+app/
+├── rbac/
+│   ├── route_permission.py        # 路由权限检查模块（新建）
+│   ├── permission_checker.py      # 现有权限检查模块
+│   └── data_scope_injector.py     # 现有数据范围注入模块
+├── routes/
+│   └── rbac_routes.py             # RBAC 路由管理接口（新建）
+```
+
+### 核心模块：route_permission.py
+
+```python
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+路由权限检查模块
+
+提供基于角色的路由权限检查功能
+"""
+
+from typing import List, Dict, Optional, Set
+import asyncpg
+from core.database import get_asyncpg_pool
+from core.redis_client import get_redis_client
+from core.logger import rbac_logger
+import json
+
+class RoutePermission:
+    """路由权限管理器"""
+
+    # Redis 缓存键前缀
+    CACHE_PREFIX = "rbac:routes"
+    CACHE_TTL = 1800  # 30分钟
+
+    @classmethod
+    async def get_user_routes(
+        cls,
+        user_id: int,
+        use_cache: bool = True
+    ) -> List[Dict]:
+        """
+        获取用户可访问的路由列表
+
+        Args:
+            user_id: 用户ID
+            use_cache: 是否使用缓存
+
+        Returns:
+            路由列表（树形结构）
+        """
+        # 1. 尝试从缓存获取
+        if use_cache:
+            cached = await cls._get_routes_from_cache(user_id)
+            if cached is not None:
+                rbac_logger.info(f"路由权限缓存命中: user={user_id}")
+                return cached
+
+        # 2. 查询用户角色
+        pool = await get_asyncpg_pool()
+        async with pool.acquire() as conn:
+            roles = await conn.fetch(
+                """
+                SELECT r.id, r.role_key, r.role_name
+                FROM user_role ur
+                JOIN roles r ON ur.role_id = r.id
+                WHERE ur.user_id = $1
+                """,
+                user_id
+            )
+
+            if not roles:
+                rbac_logger.warning(f"用户无角色: user={user_id}")
+                return []
+
+            role_ids = [role['id'] for role in roles]
+
+            # 3. 查询角色可访问的路由
+            routes = await conn.fetch(
+                """
+                SELECT DISTINCT
+                    sr.id,
+                    sr.route_path,
+                    sr.route_name,
+                    sr.component,
+                    sr.parent_id,
+                    sr.route_title,
+                    sr.icon,
+                    sr.sort_order,
+                    sr.is_hidden,
+                    sr.is_cache,
+                    sr.meta
+                FROM role_route rr
+                JOIN sys_routes sr ON rr.route_id = sr.id
+                WHERE rr.role_id = ANY($1)
+                  AND sr.status = 0
+                  AND sr.deleted_at IS NULL
+                ORDER BY sr.sort_order, sr.id
+                """,
+                role_ids
+            )
+
+            # 4. 转换为字典列表
+            route_list = [dict(route) for route in routes]
+
+            # 5. 构建树形结构
+            route_tree = cls._build_route_tree(route_list)
+
+            # 6. 缓存结果
+            if use_cache:
+                await cls._cache_routes(user_id, route_tree)
+
+            rbac_logger.info(f"查询用户路由: user={user_id}, routes={len(route_list)}")
+            return route_tree
+
+    @classmethod
+    async def get_role_routes(
+        cls,
+        role_id: int,
+        use_cache: bool = True
+    ) -> List[Dict]:
+        """
+        获取角色可访问的路由列表
+
+        Args:
+            role_id: 角色ID
+            use_cache: 是否使用缓存
+
+        Returns:
+            路由列表
+        """
+        # 缓存键
+        cache_key = f"{cls.CACHE_PREFIX}:role:{role_id}"
+
+        # 1. 尝试从缓存获取
+        if use_cache:
+            redis = await get_redis_client()
+            try:
+                cached = await redis.get(cache_key)
+                if cached:
+                    rbac_logger.info(f"角色路由缓存命中: role={role_id}")
+                    return json.loads(cached)
+            except Exception as e:
+                rbac_logger.warning(f"读取路由缓存失败: {e}")
+
+        # 2. 查询数据库
+        pool = await get_asyncpg_pool()
+        async with pool.acquire() as conn:
+            routes = await conn.fetch(
+                """
+                SELECT
+                    sr.id,
+                    sr.route_path,
+                    sr.route_name,
+                    sr.route_title
+                FROM role_route rr
+                JOIN sys_routes sr ON rr.route_id = sr.id
+                WHERE rr.role_id = $1
+                  AND sr.status = 0
+                  AND sr.deleted_at IS NULL
+                ORDER BY sr.sort_order
+                """,
+                role_id
+            )
+
+            route_list = [dict(route) for route in routes]
+
+            # 3. 缓存结果
+            if use_cache:
+                redis = await get_redis_client()
+                try:
+                    await redis.setex(
+                        cache_key,
+                        cls.CACHE_TTL,
+                        json.dumps(route_list, ensure_ascii=False)
+                    )
+                except Exception as e:
+                    rbac_logger.warning(f"缓存路由失败: {e}")
+
+            return route_list
+
+    @classmethod
+    async def check_route_access(
+        cls,
+        user_id: int,
+        route_path: str
+    ) -> bool:
+        """
+        检查用户是否有访问指定路由的权限
+
+        Args:
+            user_id: 用户ID
+            route_path: 路由路径
+
+        Returns:
+            是否有权限
+        """
+        routes = await cls.get_user_routes(user_id, use_cache=True)
+
+        # 递归检查路由树
+        def check_in_tree(routes_list: List[Dict]) -> bool:
+            for route in routes_list:
+                if route['route_path'] == route_path:
+                    return True
+                if route.get('children'):
+                    if check_in_tree(route['children']):
+                        return True
+            return False
+
+        has_access = check_in_tree(routes)
+
+        rbac_logger.info(
+            f"路由访问检查: user={user_id}, route={route_path}, "
+            f"result={has_access}"
+        )
+
+        return has_access
+
+    @classmethod
+    def _build_route_tree(cls, routes: List[Dict]) -> List[Dict]:
+        """
+        构建路由树形结构
+
+        Args:
+            routes: 路由列表（扁平）
+
+        Returns:
+            路由树（嵌套）
+        """
+        # 按 parent_id 分组
+        route_map = {}
+        root_routes = []
+
+        for route in routes:
+            route_id = route['id']
+            route_map[route_id] = route
+            route['children'] = []
+
+        # 构建父子关系
+        for route in routes:
+            parent_id = route.get('parent_id')
+            if parent_id and parent_id in route_map:
+                route_map[parent_id]['children'].append(route)
+            else:
+                root_routes.append(route)
+
+        # 移除空 children
+        def remove_empty_children(routes_list):
+            for route in routes_list:
+                if not route['children']:
+                    del route['children']
+                else:
+                    remove_empty_children(route['children'])
+
+        remove_empty_children(root_routes)
+
+        return root_routes
+
+    @classmethod
+    async def _get_routes_from_cache(cls, user_id: int) -> Optional[List[Dict]]:
+        """从缓存获取路由列表"""
+        cache_key = f"{cls.CACHE_PREFIX}:user:{user_id}"
+        redis = await get_redis_client()
+
+        try:
+            cached = await redis.get(cache_key)
+            if cached:
+                return json.loads(cached)
+        except Exception as e:
+            rbac_logger.warning(f"读取路由缓存失败: {e}")
+
+        return None
+
+    @classmethod
+    async def _cache_routes(cls, user_id: int, routes: List[Dict]):
+        """缓存路由列表"""
+        cache_key = f"{cls.CACHE_PREFIX}:user:{user_id}"
+        redis = await get_redis_client()
+
+        try:
+            await redis.setex(
+                cache_key,
+                cls.CACHE_TTL,
+                json.dumps(routes, ensure_ascii=False)
+            )
+        except Exception as e:
+            rbac_logger.warning(f"缓存路由失败: {e}")
+
+    @classmethod
+    async def clear_user_routes_cache(cls, user_id: int):
+        """清除用户路由缓存"""
+        cache_key = f"{cls.CACHE_PREFIX}:user:{user_id}"
+        redis = await get_redis_client()
+
+        try:
+            await redis.delete(cache_key)
+            rbac_logger.info(f"清除路由缓存: user={user_id}")
+        except Exception as e:
+            rbac_logger.warning(f"清除路由缓存失败: {e}")
+
+    @classmethod
+    async def clear_role_routes_cache(cls, role_id: int):
+        """清除角色路由缓存"""
+        cache_key = f"{cls.CACHE_PREFIX}:role:{role_id}"
+        redis = await get_redis_client()
+
+        try:
+            await redis.delete(cache_key)
+            rbac_logger.info(f"清除角色路由缓存: role={role_id}")
+        except Exception as e:
+            rbac_logger.warning(f"清除角色路由缓存失败: {e}")
+```
+
+### API 接口：rbac_routes.py
+
+```python
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+RBAC 路由管理接口
+
+提供路由权限相关的 API 端点
+"""
+
+from fastapi import APIRouter, Depends, Query
+from typing import List, Dict, Optional
+from pydantic import BaseModel, Field
+
+from app.rbac.route_permission import RoutePermission
+from app.auth.auth import verify_token, User
+from app.base_api import unified_resp
+from core.logger import api_logger
+
+router_rbac = APIRouter(prefix="/rbac", tags=["RBAC-路由权限"])
+
+
+class RouteResponse(BaseModel):
+    """路由响应模型"""
+    id: int
+    route_path: str
+    route_name: str
+    component: Optional[str]
+    parent_id: Optional[int]
+    route_title: str
+    icon: Optional[str]
+    sort_order: int
+    is_hidden: bool
+    is_cache: bool
+    meta: Optional[Dict]
+    children: Optional[List['RouteResponse']] = None
+
+
+class UserRoutesResponse(BaseModel):
+    """用户路由响应"""
+    user_id: int
+    username: str
+    routes: List[RouteResponse]
+
+
+@router_rbac.get("/user/routes", summary="获取当前用户可访问路由")
+@unified_resp
+async def get_current_user_routes(
+    current_user: User = Depends(verify_token)
+) -> Dict:
+    """
+    获取当前用户可访问的路由列表（树形结构）
+
+    返回数据用于前端动态路由和菜单生成
+    """
+    try:
+        routes = await RoutePermission.get_user_routes(
+            user_id=current_user.id,
+            use_cache=True
+        )
+
+        api_logger.info(f"获取用户路由: user={current_user.id}, count={len(routes)}")
+
+        return {
+            'user_id': current_user.id,
+            'username': current_user.username,
+            'routes': routes
+        }
+
+    except Exception as e:
+        api_logger.error(f"获取用户路由失败: {e}", exc_info=True)
+        raise
+
+
+@router_rbac.get("/roles/{role_id}/routes", summary="获取角色可访问路由")
+@unified_resp
+async def get_role_routes(
+    role_id: int,
+    current_user: User = Depends(verify_token)
+) -> Dict:
+    """
+    获取指定角色可访问的路由列表
+
+    用于角色管理页面展示角色权限
+    """
+    try:
+        routes = await RoutePermission.get_role_routes(
+            role_id=role_id,
+            use_cache=True
+        )
+
+        api_logger.info(f"获取角色路由: role={role_id}, count={len(routes)}")
+
+        return {
+            'role_id': role_id,
+            'routes': routes
+        }
+
+    except Exception as e:
+        api_logger.error(f"获取角色路由失败: {e}", exc_info=True)
+        raise
+
+
+@router_rbac.get("/check-route", summary="检查路由访问权限")
+@unified_resp
+async def check_route_access(
+    route_path: str = Query(..., description="路由路径"),
+    current_user: User = Depends(verify_token)
+) -> Dict:
+    """
+    检查当前用户是否有访问指定路由的权限
+
+    前端可用此接口动态控制按钮/链接显示
+    """
+    try:
+        has_access = await RoutePermission.check_route_access(
+            user_id=current_user.id,
+            route_path=route_path
+        )
+
+        return {
+            'route_path': route_path,
+            'has_access': has_access
+        }
+
+    except Exception as e:
+        api_logger.error(f"检查路由权限失败: {e}", exc_info=True)
+        raise
+```
+
+---
+
+## 前端实现
+
+### 1. 路由配置（Vue3 + Vue Router 4）
+
+```javascript
+// router/index.js
+import { createRouter, createWebHistory } from 'vue-router'
+import { useUserStore } from '@/stores/user'
+
+// 静态路由（无需权限）
+const constantRoutes = [
+  {
+    path: '/login',
+    name: 'Login',
+    component: () => import('@/views/Login.vue'),
+    meta: { title: '登录' }
+  },
+  {
+    path: '/403',
+    name: 'Forbidden',
+    component: () => import('@/views/error/403.vue'),
+    meta: { title: '无权限' }
+  },
+  {
+    path: '/404',
+    name: 'NotFound',
+    component: () => import('@/views/error/404.vue'),
+    meta: { title: '页面不存在' }
+  }
+]
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: constantRoutes
+})
+
+// 全局路由守卫
+router.beforeEach(async (to, from, next) => {
+  const userStore = useUserStore()
+  const token = localStorage.getItem('access_token')
+
+  // 白名单路由
+  const whiteList = ['/login', '/403', '/404']
+
+  if (token) {
+    if (to.path === '/login') {
+      next('/')
+      return
+    }
+
+    // 检查是否已加载动态路由
+    if (!userStore.hasLoadedRoutes) {
+      try {
+        // 获取用户路由
+        await userStore.loadUserRoutes()
+
+        // 动态添加路由
+        const dynamicRoutes = userStore.routes
+        dynamicRoutes.forEach(route => {
+          router.addRoute(route)
+        })
+
+        // 标记已加载
+        userStore.hasLoadedRoutes = true
+
+        // 重新导航到目标路由
+        next({ ...to, replace: true })
+        return
+      } catch (error) {
+        console.error('加载路由失败:', error)
+        // 清除 token，跳转登录
+        localStorage.removeItem('access_token')
+        next('/login')
+        return
+      }
+    }
+
+    // 检查路由权限
+    if (!userStore.hasRoute(to.path)) {
+      next('/403')
+      return
+    }
+
+    next()
+  } else {
+    // 未登录
+    if (whiteList.includes(to.path)) {
+      next()
+    } else {
+      next(`/login?redirect=${to.path}`)
+    }
+  }
+})
+
+export default router
+```
+
+### 2. Pinia Store（用户状态管理）
+
+```javascript
+// stores/user.js
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import apiClient from '@/utils/request'
+
+export const useUserStore = defineStore('user', () => {
+  const userInfo = ref(null)
+  const routes = ref([])
+  const hasLoadedRoutes = ref(false)
+
+  // 加载用户路由
+  async function loadUserRoutes() {
+    try {
+      const response = await apiClient.get('/rbac/user/routes')
+      const data = response.data
+
+      userInfo.value = {
+        user_id: data.user_id,
+        username: data.username
+      }
+
+      // 转换后端路由为 Vue Router 格式
+      routes.value = convertRoutes(data.routes)
+
+      // 存储到 LocalStorage
+      localStorage.setItem('user_routes', JSON.stringify(data.routes))
+
+      return routes.value
+    } catch (error) {
+      console.error('加载用户路由失败:', error)
+      throw error
+    }
+  }
+
+  // 转换路由格式
+  function convertRoutes(backendRoutes) {
+    return backendRoutes.map(route => {
+      const vueRoute = {
+        path: route.route_path,
+        name: route.route_name,
+        component: () => import(`@/views/${route.component}`),
+        meta: {
+          title: route.route_title,
+          icon: route.icon,
+          hidden: route.is_hidden,
+          keepAlive: route.is_cache,
+          ...route.meta
+        }
+      }
+
+      // 递归处理子路由
+      if (route.children && route.children.length > 0) {
+        vueRoute.children = convertRoutes(route.children)
+      }
+
+      return vueRoute
+    })
+  }
+
+  // 检查是否有指定路由权限
+  function hasRoute(path) {
+    const checkInRoutes = (routeList) => {
+      for (const route of routeList) {
+        if (route.path === path) {
+          return true
+        }
+        if (route.children && checkInRoutes(route.children)) {
+          return true
+        }
+      }
+      return false
+    }
+
+    return checkInRoutes(routes.value)
+  }
+
+  // 清除路由数据
+  function clearRoutes() {
+    routes.value = []
+    hasLoadedRoutes.value = false
+    localStorage.removeItem('user_routes')
+  }
+
+  return {
+    userInfo,
+    routes,
+    hasLoadedRoutes,
+    loadUserRoutes,
+    hasRoute,
+    clearRoutes
+  }
+})
+```
+
+### 3. 动态菜单生成
+
+```vue
+<!-- components/Sidebar.vue -->
+<template>
+  <el-menu
+    :default-active="activeMenu"
+    :collapse="isCollapse"
+    :unique-opened="true"
+    router
+  >
+    <sidebar-item
+      v-for="route in menuRoutes"
+      :key="route.path"
+      :item="route"
+    />
+  </el-menu>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+import { useUserStore } from '@/stores/user'
+import SidebarItem from './SidebarItem.vue'
+
+const route = useRoute()
+const userStore = useUserStore()
+
+// 当前激活菜单
+const activeMenu = computed(() => route.path)
+
+// 菜单路由（过滤隐藏的路由）
+const menuRoutes = computed(() => {
+  return filterHiddenRoutes(userStore.routes)
+})
+
+// 过滤隐藏路由
+function filterHiddenRoutes(routes) {
+  return routes
+    .filter(route => !route.meta?.hidden)
+    .map(route => {
+      if (route.children) {
+        route.children = filterHiddenRoutes(route.children)
+      }
+      return route
+    })
+}
+</script>
+```
+
+```vue
+<!-- components/SidebarItem.vue -->
+<template>
+  <div>
+    <!-- 有子菜单 -->
+    <el-sub-menu v-if="hasChildren" :index="item.path">
+      <template #title>
+        <el-icon v-if="item.meta?.icon">
+          <component :is="item.meta.icon" />
+        </el-icon>
+        <span>{{ item.meta?.title }}</span>
+      </template>
+      <sidebar-item
+        v-for="child in item.children"
+        :key="child.path"
+        :item="child"
+      />
+    </el-sub-menu>
+
+    <!-- 无子菜单 -->
+    <el-menu-item v-else :index="item.path">
+      <el-icon v-if="item.meta?.icon">
+        <component :is="item.meta.icon" />
+      </el-icon>
+      <span>{{ item.meta?.title }}</span>
+    </el-menu-item>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps({
+  item: {
+    type: Object,
+    required: true
+  }
+})
+
+const hasChildren = computed(() => {
+  return props.item.children && props.item.children.length > 0
+})
+</script>
+```
+
+---
+
+## 安全策略
+
+### 1. 前后端双重验证
+
+```
+前端路由守卫（第一层防护）
+  ↓
+后端 API 权限校验（第二层防护）
+  ↓
+PostgREST 数据权限（第三层防护）
+```
+
+### 2. Token 防篡改
+
+- JWT 签名验证
+- Token 有效期控制（24小时）
+- Token 刷新机制
+
+### 3. 路由访问审计
+
+记录所有路由访问日志：
+
+```python
+# 在路由守卫中记录审计日志
+await AuditLogger.log_route_access(
+    user_id=user_id,
+    route_path=route_path,
+    is_allowed=has_access,
+    ip_address=request.client.host
+)
+```
+
+### 4. 最小权限原则
+
+- 默认拒绝所有访问
+- 显式授权才能访问
+- 未配置的路由一律返回 403
+
+---
+
+## 性能优化
+
+### 1. 缓存策略
+
+| 缓存层级 | 存储位置 | TTL | 说明 |
+|---------|---------|-----|------|
+| 用户路由缓存 | Redis | 30分钟 | 用户可访问路由列表 |
+| 角色路由缓存 | Redis | 30分钟 | 角色可访问路由列表 |
+| 前端路由缓存 | LocalStorage | 登录期间 | 前端动态路由数据 |
+
+### 2. 懒加载
+
+```javascript
+// 路由组件按需加载
+component: () => import('@/views/system/Users.vue')
+```
+
+### 3. 数据库优化
+
+- 索引优化：`parent_id`、`role_id`、`route_id`
+- 查询优化：使用 JOIN 减少查询次数
+- 连接池：复用数据库连接
+
+---
+
+## 实施步骤
+
+### 阶段一：数据库准备（第1天）
+
+1. ✅ 检查 `sys_routes` 和 `role_route` 表结构
+2. ✅ 添加缺失字段（如 `icon`、`is_hidden` 等）
+3. ✅ 创建索引
+4. ✅ 编写初始化数据 SQL（系统路由 + 角色-路由关联）
+
+### 阶段二：后端实现（第2天）
+
+1. ✅ 实现 `RoutePermission` 模块
+2. ✅ 实现 `/rbac/user/routes` 接口
+3. ✅ 实现 `/rbac/roles/{role_id}/routes` 接口
+4. ✅ 实现 `/rbac/check-route` 接口
+5. ✅ 集成到现有认证流程
+
+### 阶段三：前端对接文档（第2天）
+
+1. ✅ 编写接口文档
+2. ✅ 编写前端集成示例（Vue3）
+3. ✅ 编写路由守卫示例
+4. ✅ 编写动态菜单示例
+
+### 阶段四：测试验证（第3天）
+
+1. ✅ 编写单元测试
+2. ✅ 编写集成测试
+3. ✅ 性能测试（缓存命中率、响应时间）
+4. ✅ 安全测试（未授权访问、Token 篡改）
+
+---
+
+## 测试方案
+
+### 1. 单元测试
+
+```python
+# tests/test_route_permission.py
+async def test_get_user_routes():
+    """测试获取用户路由"""
+    routes = await RoutePermission.get_user_routes(user_id=5)
+    assert len(routes) > 0
+    assert routes[0]['route_path'] == '/dashboard'
+
+
+async def test_check_route_access_allowed():
+    """测试路由访问权限（有权限）"""
+    has_access = await RoutePermission.check_route_access(
+        user_id=5,
+        route_path='/system/users'
+    )
+    assert has_access == True
+
+
+async def test_check_route_access_denied():
+    """测试路由访问权限（无权限）"""
+    has_access = await RoutePermission.check_route_access(
+        user_id=9,
+        route_path='/system/roles'
+    )
+    assert has_access == False
+```
+
+### 2. 集成测试
+
+```python
+# tests/test_rbac_routes_api.py
+async def test_get_current_user_routes_api():
+    """测试获取当前用户路由接口"""
+    response = await client.get(
+        '/rbac/user/routes',
+        headers={'Authorization': f'Bearer {token}'}
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert 'routes' in data
+    assert len(data['routes']) > 0
+```
+
+### 3. 性能测试
+
+- 缓存命中率 > 95%
+- 接口响应时间 < 100ms
+- 并发 1000 QPS 无压力
+
+---
+
+## 风险评估与应对
+
+### 风险1：Redis 不可用
+
+**应对**：降级策略，直接查询数据库
+
+### 风险2：路由数据量大（>1000条）
+
+**应对**：
+- 分页加载
+- 按需加载子菜单
+- 前端虚拟滚动
+
+### 风险3：缓存一致性
+
+**应对**：
+- 更新路由时清除相关缓存
+- 设置合理的 TTL（30分钟）
+- 提供手动刷新缓存接口
+
+---
+
+**文档版本**: v1.0
+**最后更新**: 2025-11-17
+**维护者**: DocAuditAI Team
diff --git a/tmp/交叉评查-提出意见.png b/tmp/交叉评查-提出意见.png
deleted file mode 100644
index ddca6a9..0000000
Binary files a/tmp/交叉评查-提出意见.png and /dev/null differ
diff --git a/tmp/交叉评查上传文件页面.png b/tmp/交叉评查上传文件页面.png
deleted file mode 100644
index dc1389f..0000000
Binary files a/tmp/交叉评查上传文件页面.png and /dev/null differ
diff --git a/tmp/交叉评查任务列表.png b/tmp/交叉评查任务列表.png
deleted file mode 100644
index 5609bb7..0000000
Binary files a/tmp/交叉评查任务列表.png and /dev/null differ