4.6 KiB
4.6 KiB
V1 页面与路由设计文档
1. 页面设计目标
V1 页面使用 Django Templates，优先保证清晰、稳定、可讲解。页面应围绕复试演示的主路径组织：选择场景、上传文档、入库、对话、查看审计。
2. 页面列表
| 页面 | 路径 | 模块 | 说明 |
|---|---|---|---|
| 首页/场景列表 | / |
Scenarios | 展示 5 个预置场景 |
| Agent 对话页 | /chat/<scenario_id>/ |
Chat | 提交问题并展示结果 |
| 文件列表页 | /documents/ |
Documents | 查看上传文件和入库状态 |
| 文件上传页 | /documents/upload/ |
Documents | 上传题目材料 |
| 文档入库动作 | /documents/<id>/index/ |
Documents | POST 触发入库 |
| 审计日志列表 | /audit/ |
Audit | 查看对话记录 |
| 审计日志详情 | /audit/<log_id>/ |
Audit | 查看单次执行详情 |
| Django Admin | /admin/ |
Config | 后台管理 |
3. 路由总览
config.urls
|-- "" -> apps.scenarios.urls
|-- "chat/" -> apps.chat.urls
|-- "documents/" -> apps.documents.urls
|-- "audit/" -> apps.audit.urls
|-- "admin/" -> django.contrib.admin
各模块只暴露自己的 URL，避免把业务路由集中写在 config.urls 中。
4. 首页与场景列表页
路径：/
展示内容：
- 系统名称和简短定位。
- 5 个场景卡片或列表。
- 场景名称、描述、适用题型、启用状态。
- “进入对话”按钮。
- 文件管理和审计日志入口。
错误状态：
- 没有可用场景：展示配置目录提示。
- 配置读取失败：展示失败原因和文件名。
5. Agent 对话页
路径：/chat/<scenario_id>/
页面区域：
- 场景摘要：名称、角色、目标、RAG 状态、工具列表。
- 文档范围：当前场景下状态为
indexed的文档多选框；未选择时默认使用全部已入库文档。 - 输入区：一个 textarea 和提交按钮。
- 结果区：自然语言回答和结构化输出。
- 引用区：source、chunk_id、score、content。
- 工具区：tool_name、success、arguments、result、error。
- 审计入口：当前对话生成日志后展示详情链接。
POST 成功后仍渲染同一页面，保留用户问题和 AgentResult。
6. 文件上传页
路径：/documents/upload/
页面元素：
- 场景选择下拉框。
- 文件选择控件。
- 支持类型提示。
- 上传按钮。
- 错误或成功提示。
表单接受 .txt、.md、.pdf、.docx。PDF 仅要求纯文本抽取，DOCX 仅要求段落和普通文本抽取。
7. 文件列表页
路径：/documents/
展示字段：
- 原始文件名。
- 所属场景。
- 文件类型。
- 文件大小。
- 入库状态。
- 上传时间。
- 入库按钮。
- 失败原因。
状态为 indexed 时可以显示“重新入库”，重新入库需要覆盖或清理该文档旧 chunk。
8. 审计日志列表页
路径：/audit/
展示字段：
- 日志 ID。
- 场景名称。
- 用户输入摘要。
- 状态。
- 模型名称。
- 执行耗时。
- 创建时间。
- 详情入口。
默认按 created_at desc 排序。
9. 审计日志详情页
路径：/audit/<log_id>/
展示内容：
- 场景信息。
- 用户输入。
- 最终回答。
- 结构化输出 JSON。
- RAG 引用列表。
- 工具调用列表。
- 模型名称和耗时。
- 错误信息。
JSON 内容可以先用 <pre> 展示，优先保证可读。
10. Django Admin 页面
Admin 注册：
UploadedDocumentAgentAuditLogDemoBusinessRecord
V1 不要求在 Admin 中编辑 YAML 场景，场景仍以配置文件为准。
11. 页面跳转关系
首页
|-- 进入对话页
|-- 文件列表页
|-- 审计日志列表页
文件列表页
|-- 文件上传页
|-- 触发入库后回到文件列表页
对话页
|-- 提交后留在当前对话页
|-- 查看当前审计详情
审计列表页
|-- 审计详情页
12. 页面异常状态
| 页面 | 异常 | 展示方式 |
|---|---|---|
| 首页 | 场景配置为空 | 空状态和配置目录说明 |
| 对话页 | 场景不存在 | 明确提示并提供返回首页 |
| 对话页 | Agent 执行失败 | 展示错误、保留输入、写入失败审计 |
| 上传页 | 文件类型错误 | 表单错误 |
| 文件列表 | 入库失败 | 状态为 failed 并显示原因 |
| 审计详情 | 日志不存在 | 404 或友好错误页 |
13. V1 页面验收标准
- 主要页面可通过浏览器访问。
- 页面之间跳转路径完整。
- POST 表单使用 CSRF 保护。
- 所有用户可见错误都有中文提示。
- Agent 对话结果可以同时看到回答、引用、工具和审计入口。
- 页面不依赖 React/Vue。