# 项目路由文档 ## 目录 - [认证相关路由](#认证相关路由) - [主页路由](#主页路由) - [文档管理路由](#文档管理路由) - [交叉评查路由](#交叉评查路由) - [合同模板路由](#合同模板路由) - [AI对话路由](#ai对话路由) - [配置管理路由](#配置管理路由) - [API路由](#api路由) - [示例与调试路由](#示例与调试路由) --- ## 认证相关路由 ### 1. `/login` - 登录页 **文件：** `app/routes/login.tsx` **功能：** - 双登录模式：OAuth2.0统一身份认证 + 管理员账号密码登录 - 卡片翻转动画切换登录方式 - OAuth登录流程：生成state → 跳转IDaaS → 回调处理 - 管理员登录：调用后端API验证账号密码 **Loader：** - 检查用户是否已登录，已登录则重定向到首页 - 读取session中的错误信息（来自OAuth回调） - 保存重定向目标URL到session **关键逻辑：** ```typescript // OAuth登录 const oauthClient = new OAuthClient(CLIENT_OAUTH_CONFIG); const state = oauthClient.generateState(); const authorizeUrl = oauthClient.getAuthorizeUrl(state); window.location.href = authorizeUrl; // 管理员登录 const response = await loginWithPassword(username, password); storeLoginData(access_token, user_info); ``` --- ### 2. `/callback` - OAuth回调 **文件：** `app/routes/callback.tsx` **功能：** - 处理OAuth2.0授权回调 - 验证state参数防止CSRF攻击 - 获取访问令牌（access_token） - 获取用户信息 - 调用后端登录接口获取JWT - 创建用户session **Loader流程：** 1. 验证回调参数（code、state、error） 2. 使用code交换access_token 3. 使用access_token获取用户信息 4. 调用`loginWithOAuth`接口同步用户到本地数据库 5. 创建前端JWT并存储到session 6. 重定向到目标页面 **端口到地区映射：** ```typescript const PORT_TO_AREA_MAP = { '51703': '梅州', '51704': '云浮', '51705': '揭阳', '51706': '潮州', '51707': '省局' }; ``` **错误处理：** - OAuth失败：调用IDaaS登出，清除登录状态 - 使用session flash传递错误信息到登录页 --- ### 3. `/logout` - 登出 **文件：** `app/routes/logout.tsx` **功能：** - 清除本地session - 调用IDaaS单点登出（仅OAuth用户） - 重定向到登录页 **Loader逻辑：** ```typescript const isAdmin = userRole === 'admin'; if (accessToken && !isAdmin) { // 调用IDaaS登出 await oauthClient.logout(accessToken, redirectUrl); } // 销毁session await sessionStorage.destroySession(session); ``` --- ## 主页路由 ### 4. `/` - 入口页 **文件：** `app/routes/_index.tsx` **功能：** - 欢迎页面，展示三大功能模块 - 根据端口号动态显示/隐藏模块 - 实时显示日期时间 - 用户信息展示与登出 **模块导航：** 1. **合同管理** → `/contract-template/search`（51707端口隐藏） 2. **案卷智能评查** → `/home` 3. **智慧法务大模型** → `/chat-with-llm` **端口限制：** - 端口51707（省局）：隐藏合同管理模块 - 其他端口：显示全部三个模块 **Loader：** - 验证用户登录状态 - 未登录重定向到`/login` --- ### 5. `/home` - 系统概览（首页） **文件：** `app/routes/home.tsx` **功能：** - 数据统计仪表盘 - 快捷访问入口 - 最近文档列表 - 实时数据刷新（10秒轮询） **核心数据：** 1. **今日待审文件数** 2. **本月已审核文件数**（含同比增长） 3. **本月审核通过率**（含同比增长） 4. **本月问题检出数**（含同比增长） **客户端逻辑：** - 从`sessionStorage`读取`reviewType`（contract/record） - 根据类型加载对应统计数据 - 监听`reviewType`变化自动刷新数据 - 每10秒自动刷新最近文档列表 **Loader：** - 返回初始空数据（实际数据由客户端异步加载） - 传递`userRole`、`userInfo`、`frontendJWT` --- ## 文档管理路由 ### 6. `/documents` - 文档列表（布局） **文件：** `app/routes/documents.tsx` **功能：** 嵌套路由容器，提供面包屑导航 --- ### 7. `/documents` (Index) - 文档列表页 **文件：** `app/routes/documents._index.tsx` **功能：** - 文档搜索与筛选 - 分页显示文档列表 - 查看文档详情 - 文档上传、编辑、删除 **筛选条件：** - 文档名称搜索 - 文档类型过滤 - 审核状态过滤 - 时间范围筛选 --- ### 8. `/documents/upload` - 文档上传 **文件：** `app/routes/documents.upload.tsx` **功能：** - 文件上传（PDF/DOCX） - 文档类型选择 - 评查点配置 - 上传进度显示 --- ### 9. `/documents/edit` - 文档编辑 **文件：** `app/routes/documents.edit.tsx` **功能：** - 修改文档信息 - 更新文档类型 - 修改评查点配置 --- ### 10. `/documents/download` - 文档下载 **文件：** `app/routes/documents.download.tsx` **功能：** - 处理文档下载请求 - 支持批量下载 --- ## 交叉评查路由 ### 11. `/cross-checking` - 交叉评查（布局） **文件：** `app/routes/cross-checking.tsx` **功能：** 嵌套路由容器 --- ### 12. `/cross-checking` (Index) - 任务列表 **文件：** `app/routes/cross-checking._index.tsx` **功能：** - 交叉评查任务列表 - 任务状态筛选（待处理/进行中/已完成） - 查看任务详情 - 创建新任务 **任务状态：** - `pending` - 待处理 - `in_progress` - 进行中 - `completed` - 已完成 - `arbitrated` - 已仲裁 --- ### 13. `/cross-checking/upload` - 上传评查文档 **文件：** `app/routes/cross-checking.upload.tsx` **功能：** - 上传需要交叉评查的文档 - 分配评查人员 - 设置评查截止时间 --- ### 14. `/cross-checking/result` - 评查结果 **文件：** `app/routes/cross-checking.result.tsx` **功能：** - 查看评查结果 - 提交评分意见 - 发起提案 - 投票表决 **民主决策流程：** 1. 评查人员提交评分 2. 发起修改提案 3. 其他评查人员投票 4. 达到阈值自动通过/驳回 --- ## 合同模板路由 ### 15. `/contract-template` - 合同模板（布局） **文件：** `app/routes/contract-template.tsx` **功能：** 嵌套路由容器 --- ### 16. `/contract-template/search` - 模板搜索 **文件：** `app/routes/contract-template.search._index.tsx` **功能：** - 合同模板关键词搜索 - 模板分类浏览 - 快速筛选 --- ### 17. `/contract-template/search/results` - 搜索结果 **文件：** `app/routes/contract-template.search.results.tsx` **功能：** - 展示搜索结果列表 - 高亮关键词 - 预览模板内容 --- ### 18. `/contract-template/list` - 模板列表 **文件：** `app/routes/contract-template.list._index.tsx` **功能：** - 所有合同模板列表 - 模板分类管理 - 模板上传/下载 --- ### 19. `/contract-template/detail/:id` - 模板详情 **文件：** `app/routes/contract-template.detail.$id.tsx` **功能：** - 查看模板详细信息 - 在线预览模板内容 - 下载模板文件 **动态路由参数：** - `:id` - 模板ID --- ## AI对话路由 ### 20. `/chat-with-llm` - AI对话（布局） **文件：** `app/routes/chat-with-llm.tsx` **功能：** 嵌套路由容器 --- ### 21. `/chat-with-llm` (Index) - 对话界面 **文件：** `app/routes/chat-with-llm._index.tsx` **功能：** - AI法务助手对话界面 - 多轮对话管理 - 会话历史记录 - 文件上传辅助分析 **核心特性：** - 支持上下文对话 - 法律条文引用 - 案例分析 - 文档解读 --- ## 配置管理路由 ### 22. `/rules` - 评查点管理（布局） **文件：** `app/routes/rules.tsx` **功能：** 评查规则管理容器 **权限：** 仅开发者角色可访问 --- ### 23. `/rules` (Index) - 评查点列表 **文件：** `app/routes/rules._index.tsx` **功能：** - 评查点列表展示 - 评查点搜索与筛选 - 启用/禁用评查点 - 删除评查点 --- ### 24. `/rules/new` - 新建评查点 **文件：** `app/routes/rules-new.tsx` **功能：** - 创建新评查点 - 配置评查规则 - 设置评分标准 --- ### 25. `/rule-groups` - 评查点分组（布局） **文件：** `app/routes/rule-groups.tsx` **功能：** 评查点分组管理容器 --- ### 26. `/rule-groups` (Index) - 分组列表 **文件：** `app/routes/rule-groups._index.tsx` **功能：** - 评查点分组列表 - 分组管理（增删改） - 分配评查点到分组 --- ### 27. `/rule-groups/new` - 新建分组 **文件：** `app/routes/rule-groups.new.tsx` **功能：** - 创建新分组 - 设置分组名称和描述 --- ### 28. `/prompts` - 提示词管理（布局） **文件：** `app/routes/prompts.tsx` **功能：** 提示词模板管理容器 **权限：** 仅开发者角色可访问 --- ### 29. `/prompts` (Index) - 提示词列表 **文件：** `app/routes/prompts._index.tsx` **功能：** - AI提示词模板列表 - 提示词搜索 - 启用/禁用模板 - 删除模板 **提示词类型：** - LLM提示词（文本模型） - VLM提示词（多模态模型） --- ### 30. `/prompts/new` - 新建提示词 **文件：** `app/routes/prompts.new.tsx` **功能：** - 创建新提示词模板 - 配置提示词变量 - 预览提示词效果 --- ### 31. `/document-types` - 文档类型管理（布局） **文件：** `app/routes/document-types.tsx` **功能：** 文档类型管理容器 **权限：** 仅开发者角色可访问 --- ### 32. `/document-types` (Index) - 文档类型列表 **文件：** `app/routes/document-types._index.tsx` **功能：** - 文档类型列表 - 类型管理（增删改） - 绑定评查点模板 **预设类型：** - 类型1：合同 - 类型2：许可卷宗（类型2） - 类型3：许可卷宗（类型3） --- ### 33. `/document-types/new` - 新建文档类型 **文件：** `app/routes/document-types.new.tsx` **功能：** - 创建新文档类型 - 配置类型属性 --- ### 34. `/config-lists` - 配置列表管理（布局） **文件：** `app/routes/config-lists.tsx` **功能：** 系统配置管理容器 **权限：** 仅开发者角色可访问 --- ### 35. `/config-lists` (Index) - 配置列表 **文件：** `app/routes/config-lists._index.tsx` **功能：** - 系统配置项列表 - 配置项管理 --- ### 36. `/config-lists/new` - 新建配置 **文件：** `app/routes/config-lists.new.tsx` **功能：** - 创建新配置项 - 设置配置值 --- ## API路由 ### 37. `/api/oauth/token` - OAuth Token代理 **文件：** `app/routes/api.oauth.token.tsx` **功能：** - 代理OAuth token请求 - 避免在客户端暴露client_secret **方法：** POST --- ### 38. `/api/oauth/userinfo` - OAuth用户信息代理 **文件：** `app/routes/api.oauth.userinfo.tsx` **功能：** - 代理OAuth用户信息请求 - 返回用户基本信息 **方法：** GET --- ### 39. `/api/file-upload` - 文件上传（AI对话） **文件：** `app/routes/api.file-upload.tsx` **功能：** - 处理AI对话中的文件上传 - 使用Dify客户端上传文件 **方法：** POST **请求体：** ```typescript FormData { file: File } ``` **响应：** ```typescript { id: string // 上传ID } ``` --- ### 40. `/api/pdf-proxy` - PDF代理 **文件：** `app/routes/api.pdf-proxy.tsx` **功能：** - 代理PDF文件请求 - 解决跨域问题 - 支持PDF流式传输 **方法：** GET **查询参数：** - `url` - PDF文件URL --- ### 41. `/api/conversations` - 会话管理 **文件：** `app/routes/api.conversations.tsx` **功能：** - 获取AI对话会话列表 - 创建新会话 **方法：** GET, POST --- ### 42. `/api/conversations/:id` - 单个会话操作 **文件：** `app/routes/api.conversations.$id.tsx` **功能：** - 获取会话详情 - 删除会话 **方法：** GET, DELETE **动态参数：** - `:id` - 会话ID --- ### 43. `/api/conversations/:id/name` - 修改会话名称 **文件：** `app/routes/api.conversations.$id.name.tsx` **功能：** - 更新会话名称 **方法：** PATCH --- ### 44. `/api/chat-messages` - 发送消息 **文件：** `app/routes/api.chat-messages.tsx` **功能：** - 发送AI对话消息 - 流式响应 **方法：** POST **请求体：** ```typescript { query: string, // 用户消息 conversation_id?: string, // 会话ID（可选） files?: Array<{ // 附件（可选） type: string, transfer_method: string, upload_file_id: string }> } ``` --- ### 45. `/api/messages` - 消息历史 **文件：** `app/routes/api.messages.tsx` **功能：** - 获取会话消息历史 **方法：** GET **查询参数：** - `conversation_id` - 会话ID --- ### 46. `/api/parameters` - 应用参数 **文件：** `app/routes/api.parameters.tsx` **功能：** - 获取AI应用配置参数 **方法：** GET --- ## 示例与调试路由 ### 47. `/examples/message-modal` - 消息弹窗示例 **文件：** `app/routes/examples/message-modal.tsx` **功能：** - MessageModal组件使用示例 - 演示确认框、提示框等 --- ### 48. `/examples/toast` - Toast示例 **文件：** `app/routes/examples/toast.tsx` **功能：** - Toast组件使用示例 - 演示成功、错误、警告、信息提示 --- ### 49. `/examples/pdfview` - PDF预览示例 **文件：** `app/routes/examples/pdfview.tsx` **功能：** - PDF预览组件示例 - 演示PDF在线查看功能 --- ### 50. `/examples/TooltipExample` - Tooltip示例 **文件：** `app/routes/examples/TooltipExample.tsx` **功能：** - Tooltip组件使用示例 - 演示气泡提示效果 --- ### 51. `/debug` - 调试页面 **文件：** `app/routes/debug.tsx` **功能：** - 开发调试工具 - 查看系统状态 - 测试功能 --- ## 其他路由 ### 52. `/files` - 文件管理（布局） **文件：** `app/routes/files.tsx` **功能：** 文件管理容器 --- ### 53. `/files/upload` - 文件上传 **文件：** `app/routes/files.upload.tsx` **功能：** - 通用文件上传功能 - 支持多文件上传 --- ### 54. `/rules-files` - 评查点文件管理 **文件：** `app/routes/rules-files.tsx` **功能：** - 评查点相关文件管理 --- ### 55. `/reviews` - 评审管理 **文件：** `app/routes/reviews.tsx` **功能：** - 文档评审管理 --- ### 56. `/contract-search` - 合同搜索（布局） **文件：** `app/routes/contract-search.tsx` **功能：** 合同搜索容器（可能已废弃，被contract-template替代） --- ### 57. `/contract-search` (Index) - 合同搜索页 **文件：** `app/routes/contract-search._index.tsx` **功能：** 合同搜索功能（可能已废弃） --- ## 路由命名规范 ### 1. 文件命名模式 **布局路由（Layout）：** ``` routes/documents.tsx → /documents (布局) routes/documents._index.tsx → /documents (Index页面) routes/documents.upload.tsx → /documents/upload ``` **嵌套路由：** ``` routes/contract-template.tsx → /contract-template routes/contract-template.search._index.tsx → /contract-template/search routes/contract-template.search.results.tsx → /contract-template/search/results ``` **动态路由：** ``` routes/contract-template.detail.$id.tsx → /contract-template/detail/:id routes/api.conversations.$id.tsx → /api/conversations/:id ``` **API路由：** ``` routes/api.file-upload.tsx → /api/file-upload routes/api.oauth.token.tsx → /api/oauth/token ``` ### 2. 路由分组 | 分组 | 前缀 | 说明 | |------|------|------| | 认证 | `/login`, `/logout`, `/callback` | 用户认证流程 | | 主页 | `/`, `/home` | 系统入口和概览 | | 文档 | `/documents/*` | 文档管理功能 | | 交叉评查 | `/cross-checking/*` | 交叉评查系统 | | 合同模板 | `/contract-template/*` | 合同模板管理 | | AI对话 | `/chat-with-llm/*` | AI法务助手 | | 配置 | `/rules/*`, `/prompts/*`, `/document-types/*` | 系统配置管理 | | API | `/api/*` | 后端API代理 | | 示例 | `/examples/*` | 组件示例 | --- ## 权限控制 ### 开发者专属路由（Developer Only） 以下路由仅`developer`角色可访问： 1. `/prompts` - 提示词管理 2. `/config-lists` - 配置列表管理 3. `/document-types` - 文档类型管理 4. `/rules` - 评查点管理 **实现方式：** - 在`app/root.tsx`的loader中检查用户角色 - 侧边栏根据角色动态显示菜单项 - 路由loader中验证权限，未授权重定向 ### 端口限制路由 **端口51707（省局）限制：** - 隐藏合同管理入口（`/contract-template`） - 仅显示案卷智能评查和AI对话 **端口51708（测试实例）限制：** - 仅允许访问`/cross-checking/*`路由 - 其他路由返回403 --- ## Meta标签配置 每个路由都配置了SEO友好的meta标签： ```typescript export const meta: MetaFunction = () => { return [ { title: "页面标题 - 中国烟草AI合同及卷宗审核系统" }, { name: "description", content: "页面描述" } ]; }; ``` --- ## 面包屑导航 使用`handle`导出面包屑信息： ```typescript export const handle = { breadcrumb: "评查点列表" }; ``` 在Layout组件中读取并显示面包屑导航。 --- ## 路由加载器（Loader） ### 认证检查模式 **全局认证：** ```typescript // app/root.tsx export async function loader({ request }: LoaderFunctionArgs) { const { isAuthenticated, userRole } = await getUserSession(request); if (!isAuthenticated && !isPublicRoute(url.pathname)) { throw redirect("/login"); } return { isAuthenticated, userRole }; } ``` **路由级认证：** ```typescript export async function loader({ request }: LoaderFunctionArgs) { const { isAuthenticated } = await getUserSession(request); if (!isAuthenticated) { return redirect("/login"); } return { /* 数据 */ }; } ``` --- ## 路由操作（Action） ### 示例：登出操作 ```typescript export async function action({ request }: ActionFunctionArgs) { const formData = await request.formData(); const intent = formData.get("intent"); if (intent === "logout") { return logout(request); } return null; } ``` ### 示例：文件上传 ```typescript export async function action({ request }: ActionFunctionArgs) { const formData = await request.formData(); const file = formData.get('file') as File; // 处理文件上传 const uploadId = await uploadFile(file); return json({ id: uploadId }); } ``` --- ## 客户端状态管理 ### SessionStorage使用 **reviewType管理：** ```typescript // 保存类型 sessionStorage.setItem('reviewType', 'contract'); // 读取类型 const reviewType = sessionStorage.getItem('reviewType'); // 类型切换时刷新数据 useEffect(() => { const reviewType = sessionStorage.getItem('reviewType'); loadData(reviewType); }, []); ``` **用户信息：** ```typescript sessionStorage.setItem('userInfo', JSON.stringify(userInfo)); sessionStorage.setItem('frontendJWT', jwt); ``` --- ## 路由导航 ### 编程式导航 ```typescript import { useNavigate } from '@remix-run/react'; const navigate = useNavigate(); // 导航到指定路由 navigate('/documents'); // 带状态导航 navigate('/documents/edit', { state: { documentId: 123 } }); // 替换历史记录 navigate('/login', { replace: true }); ``` ### 声明式导航 ```typescript import { Link } from '@remix-run/react'; 文档列表 查看详情 ``` --- ## 错误处理 ### 路由级错误边界 ```typescript export function ErrorBoundary() { const error = useRouteError(); if (isRouteErrorResponse(error)) { return (

{error.status} {error.statusText}

{error.data}

); } return
发生错误
; } ``` --- ## 开发建议 ### 1. 路由组织 - 按功能模块分组 - 使用嵌套路由减少重复 - 布局路由放在顶层 ### 2. 命名规范 - 使用语义化路由名称 - 动态参数使用`$`前缀 - API路由统一使用`api.`前缀 ### 3. 性能优化 - 使用Loader预加载数据 - 避免客户端重复请求 - 使用缓存策略 ### 4. 安全性 - 所有路由都应验证认证状态 - 敏感操作检查权限 - API路由添加CSRF保护 --- ## 附录 ### 完整路由树 ``` / # 入口页（模块选择） ├── /login # 登录页 ├── /logout # 登出 ├── /callback # OAuth回调 ├── /home # 系统概览首页 │ ├── /documents # 文档管理 │ ├── / # 文档列表 │ ├── /upload # 上传文档 │ ├── /edit # 编辑文档 │ └── /download # 下载文档 │ ├── /cross-checking # 交叉评查 │ ├── / # 任务列表 │ ├── /upload # 上传评查文档 │ └── /result # 评查结果 │ ├── /contract-template # 合同模板 │ ├── /search # 模板搜索 │ │ ├── / # 搜索页 │ │ └── /results # 搜索结果 │ ├── /list # 模板列表 │ └── /detail/:id # 模板详情 │ ├── /chat-with-llm # AI对话 │ └── / # 对话界面 │ ├── /rules # 评查点管理 [开发者] │ ├── / # 评查点列表 │ └── /new # 新建评查点 │ ├── /rule-groups # 评查点分组 │ ├── / # 分组列表 │ └── /new # 新建分组 │ ├── /prompts # 提示词管理 [开发者] │ ├── / # 提示词列表 │ └── /new # 新建提示词 │ ├── /document-types # 文档类型管理 [开发者] │ ├── / # 类型列表 │ └── /new # 新建类型 │ ├── /config-lists # 配置管理 [开发者] │ ├── / # 配置列表 │ └── /new # 新建配置 │ ├── /api # API路由 │ ├── /oauth │ │ ├── /token # Token代理 │ │ └── /userinfo # 用户信息代理 │ ├── /file-upload # 文件上传 │ ├── /pdf-proxy # PDF代理 │ ├── /conversations # 会话管理 │ │ ├── / # 会话列表/创建 │ │ └── /:id # 单个会话 │ │ └── /name # 修改名称 │ ├── /chat-messages # 发送消息 │ ├── /messages # 消息历史 │ └── /parameters # 应用参数 │ └── /examples # 示例页面 ├── /message-modal # 消息弹窗示例 ├── /toast # Toast示例 ├── /pdfview # PDF预览示例 └── /TooltipExample # Tooltip示例 ``` --- **文档版本：** 1.0 **最后更新：** 2025-11-17 **维护者：** 系统开发团队