leaudit-platform-frontend/docs/routes-documentation.md

项目路由文档

目录

• 认证相关路由
• 主页路由
• 文档管理路由
• 交叉评查路由
• 合同模板路由
• AI对话路由
• 配置管理路由
• API路由
• 示例与调试路由

---

认证相关路由

1. /login - 登录页

文件： app/routes/login.tsx

功能：

• 双登录模式：OAuth2.0统一身份认证 + 管理员账号密码登录
• 卡片翻转动画切换登录方式
• OAuth登录流程：生成state → 跳转IDaaS → 回调处理
• 管理员登录：调用后端API验证账号密码

Loader：

• 检查用户是否已登录，已登录则重定向到首页
• 读取session中的错误信息（来自OAuth回调）
• 保存重定向目标URL到session

关键逻辑：

// 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. 重定向到目标页面

端口到地区映射：

const PORT_TO_AREA_MAP = {
  '51703': '梅州',
  '51704': '云浮',
  '51705': '揭阳',
  '51706': '潮州',
  '51707': '省局'
};

错误处理：

• OAuth失败：调用IDaaS登出，清除登录状态
• 使用session flash传递错误信息到登录页

---

3. /logout - 登出

文件： app/routes/logout.tsx

功能：

• 清除本地session
• 调用IDaaS单点登出（仅OAuth用户）
• 重定向到登录页

Loader逻辑：

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

请求体：

FormData {
  file: File
}

响应：

{
  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

请求体：

{
  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标签：

export const meta: MetaFunction = () => {
  return [
    { title: "页面标题 - 中国烟草AI合同及卷宗审核系统" },
    { name: "description", content: "页面描述" }
  ];
};

---

面包屑导航

使用handle导出面包屑信息：

export const handle = {
  breadcrumb: "评查点列表"
};

在Layout组件中读取并显示面包屑导航。

---

路由加载器（Loader）

认证检查模式

全局认证：

// 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 };
}

路由级认证：

export async function loader({ request }: LoaderFunctionArgs) {
  const { isAuthenticated } = await getUserSession(request);

  if (!isAuthenticated) {
    return redirect("/login");
  }

  return { /* 数据 */ };
}

---

路由操作（Action）

示例：登出操作

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const intent = formData.get("intent");

  if (intent === "logout") {
    return logout(request);
  }

  return null;
}

示例：文件上传

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管理：

// 保存类型
sessionStorage.setItem('reviewType', 'contract');

// 读取类型
const reviewType = sessionStorage.getItem('reviewType');

// 类型切换时刷新数据
useEffect(() => {
  const reviewType = sessionStorage.getItem('reviewType');
  loadData(reviewType);
}, []);

用户信息：

sessionStorage.setItem('userInfo', JSON.stringify(userInfo));
sessionStorage.setItem('frontendJWT', jwt);

---

路由导航

编程式导航

import { useNavigate } from '@remix-run/react';

const navigate = useNavigate();

// 导航到指定路由
navigate('/documents');

// 带状态导航
navigate('/documents/edit', { state: { documentId: 123 } });

// 替换历史记录
navigate('/login', { replace: true });

声明式导航

import { Link } from '@remix-run/react';

<Link to="/documents">文档列表</Link>
<Link to={`/contract-template/detail/${id}`}>查看详情</Link>

---

错误处理

路由级错误边界

export function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>{error.status} {error.statusText}</h1>
        <p>{error.data}</p>
      </div>
    );
  }

  return <div>发生错误</div>;
}

---

开发建议

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 维护者： 系统开发团队