# V1 页面与路由设计文档 ## 1. 页面设计目标 V1 页面使用 Django Templates，优先保证清晰、稳定、可讲解。页面应围绕复试演示的主路径组织：选择场景、上传文档、入库、对话、查看审计。 ## 2. 页面列表 | 页面 | 路径 | 模块 | 说明 | |---|---|---|---| | 首页/场景列表 | `/` | Scenarios | 展示 5 个预置场景 | | Agent 对话页 | `/chat//` | Chat | 提交问题并展示结果 | | 文件列表页 | `/documents/` | Documents | 查看上传文件和入库状态 | | 文件上传页 | `/documents/upload/` | Documents | 上传题目材料 | | 文档入库动作 | `/documents//index/` | Documents | POST 触发入库 | | 审计日志列表 | `/audit/` | Audit | 查看对话记录 | | 审计日志详情 | `/audit//` | 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//` 页面区域： - 场景摘要：名称、角色、目标、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//` 展示内容： - 场景信息。 - 用户输入。 - 最终回答。 - 结构化输出 JSON。 - RAG 引用列表。 - 工具调用列表。 - 模型名称和耗时。 - 错误信息。 JSON 内容可以先用 `
` 展示，优先保证可读。

## 10. Django Admin 页面

Admin 注册：

- `UploadedDocument`
- `AgentAuditLog`
- `DemoBusinessRecord`

V1 不要求在 Admin 中编辑 YAML 场景，场景仍以配置文件为准。

## 11. 页面跳转关系

```text
首页
  |-- 进入对话页
  |-- 文件列表页
  |-- 审计日志列表页

文件列表页
  |-- 文件上传页
  |-- 触发入库后回到文件列表页

对话页
  |-- 提交后留在当前对话页
  |-- 查看当前审计详情

审计列表页
  |-- 审计详情页
```

## 12. 页面异常状态

| 页面 | 异常 | 展示方式 |
|---|---|---|
| 首页 | 场景配置为空 | 空状态和配置目录说明 |
| 对话页 | 场景不存在 | 明确提示并提供返回首页 |
| 对话页 | Agent 执行失败 | 展示错误、保留输入、写入失败审计 |
| 上传页 | 文件类型错误 | 表单错误 |
| 文件列表 | 入库失败 | 状态为 failed 并显示原因 |
| 审计详情 | 日志不存在 | 404 或友好错误页 |

## 13. V1 页面验收标准

- 主要页面可通过浏览器访问。
- 页面之间跳转路径完整。
- POST 表单使用 CSRF 保护。
- 所有用户可见错误都有中文提示。
- Agent 对话结果可以同时看到回答、引用、工具和审计入口。
- 页面不依赖 React/Vue。