docs(design): 补全中文设计文档体系
This commit is contained in:
179
docs/设计文档/4.页面与路由设计.md
Normal file
179
docs/设计文档/4.页面与路由设计.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user