23 KiB
项目路由文档
目录
认证相关路由
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流程：
- 验证回调参数（code、state、error）
- 使用code交换access_token
- 使用access_token获取用户信息
- 调用
loginWithOAuth接口同步用户到本地数据库 - 创建前端JWT并存储到session
- 重定向到目标页面
端口到地区映射：
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
功能：
- 欢迎页面，展示三大功能模块
- 根据端口号动态显示/隐藏模块
- 实时显示日期时间
- 用户信息展示与登出
模块导航：
- 合同管理 →
/contract-template/search（51707端口隐藏） - 案卷智能评查 →
/home - 智慧法务大模型 →
/chat-with-llm
端口限制：
- 端口51707（省局）：隐藏合同管理模块
- 其他端口：显示全部三个模块
Loader：
- 验证用户登录状态
- 未登录重定向到
/login
5. /home - 系统概览（首页）
文件： app/routes/home.tsx
功能：
- 数据统计仪表盘
- 快捷访问入口
- 最近文档列表
- 实时数据刷新（10秒轮询）
核心数据：
- 今日待审文件数
- 本月已审核文件数（含同比增长）
- 本月审核通过率（含同比增长）
- 本月问题检出数（含同比增长）
客户端逻辑：
- 从
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
功能：
- 查看评查结果
- 提交评分意见
- 发起提案
- 投票表决
民主决策流程：
- 评查人员提交评分
- 发起修改提案
- 其他评查人员投票
- 达到阈值自动通过/驳回
合同模板路由
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角色可访问：
/prompts- 提示词管理/config-lists- 配置列表管理/document-types- 文档类型管理/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 维护者： 系统开发团队