180 lines
4.6 KiB
Markdown
180 lines
4.6 KiB
Markdown
# 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. 路由总览
|
||
|
||
```text
|
||
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 注册：
|
||
|
||
- `UploadedDocument`
|
||
- `AgentAuditLog`
|
||
- `DemoBusinessRecord`
|
||
|
||
V1 不要求在 Admin 中编辑 YAML 场景，场景仍以配置文件为准。
|
||
|
||
## 11. 页面跳转关系
|
||
|
||
```text
|
||
首页
|
||
|-- 进入对话页
|
||
|-- 文件列表页
|
||
|-- 审计日志列表页
|
||
|
||
文件列表页
|
||
|-- 文件上传页
|
||
|-- 触发入库后回到文件列表页
|
||
|
||
对话页
|
||
|-- 提交后留在当前对话页
|
||
|-- 查看当前审计详情
|
||
|
||
审计列表页
|
||
|-- 审计详情页
|
||
```
|
||
|
||
## 12. 页面异常状态
|
||
|
||
| 页面 | 异常 | 展示方式 |
|
||
|---|---|---|
|
||
| 首页 | 场景配置为空 | 空状态和配置目录说明 |
|
||
| 对话页 | 场景不存在 | 明确提示并提供返回首页 |
|
||
| 对话页 | Agent 执行失败 | 展示错误、保留输入、写入失败审计 |
|
||
| 上传页 | 文件类型错误 | 表单错误 |
|
||
| 文件列表 | 入库失败 | 状态为 failed 并显示原因 |
|
||
| 审计详情 | 日志不存在 | 404 或友好错误页 |
|
||
|
||
## 13. V1 页面验收标准
|
||
|
||
- 主要页面可通过浏览器访问。
|
||
- 页面之间跳转路径完整。
|
||
- POST 表单使用 CSRF 保护。
|
||
- 所有用户可见错误都有中文提示。
|
||
- Agent 对话结果可以同时看到回答、引用、工具和审计入口。
|
||
- 页面不依赖 React/Vue。
|