222 lines
8.3 KiB
Markdown
222 lines
8.3 KiB
Markdown
---
|
|
reviewStatus: pending
|
|
reviewedAt: null
|
|
replacedBy: null
|
|
---
|
|
|
|
# 第一阶段工程基线前端落地设计
|
|
|
|
## 1. 文档定位
|
|
|
|
本文档定义第一阶段 Django 服务端页面的页面结构、路由、交互、状态、权限与可访问性边界。当前项目没有独立前端框架或组件库，因此本阶段使用 Django Templates、Django Forms 和少量原生 CSS，不引入 Vue、React、前端状态库或前后端分离架构。
|
|
|
|
关联设计：
|
|
|
|
- [后端落地设计](backend-design.md)
|
|
- [数据库设计](database-design.md)
|
|
- [接口与页面契约设计](interface-design.md)
|
|
- [第一阶段工程基线开发计划](../../../docs/engineering-baseline/dev-plan.md)
|
|
|
|
## 2. 用户角色与核心场景
|
|
|
|
### 2.1 未登录访问者
|
|
|
|
- 可以进入登录页。
|
|
- 访问个人资料和运行页面时跳转登录页。
|
|
- 不提供公开注册入口。
|
|
|
|
### 2.2 普通用户
|
|
|
|
- 登录和退出系统。
|
|
- 查看、修改自己的基础资料。
|
|
- 查看自己的 Agent Run 列表。
|
|
- 查看自己的 Agent Run 详情、事件和工具调用摘要。
|
|
- 不能查看其他用户的数据，也不能从页面执行真实 Agent 任务。
|
|
|
|
### 2.3 管理员
|
|
|
|
- 使用 Django Admin 创建和停用用户。
|
|
- 查看全部用户资料和 Agent 运行记录。
|
|
- 创建用于验证持久化链路的最小 Run。
|
|
- 在 Admin 中处理待确认记录。
|
|
|
|
## 3. 页面与路由
|
|
|
|
| 页面 | 路由 | 访问角色 | 主要操作 |
|
|
| --- | --- | --- | --- |
|
|
| 登录 | `/accounts/login/` | 未登录用户 | 提交用户名和密码 |
|
|
| 退出 | `/accounts/logout/` | 已登录用户 | POST 确认退出 |
|
|
| 个人资料 | `/accounts/profile/` | 普通用户、管理员 | 查看和修改自己的资料 |
|
|
| 运行列表 | `/runs/` | 普通用户、管理员 | 查看当前用户的运行记录 |
|
|
| 运行详情 | `/runs/<uuid>/` | 记录所属用户、管理员 | 查看状态、事件和工具调用摘要 |
|
|
| API 服务商 | `/runs/providers/` | 普通用户、管理员 | 搜索、筛选并配置自己的模型服务商 |
|
|
| 管理后台 | `/admin/` | 管理员 | 管理用户和审计记录 |
|
|
|
|
登录成功默认进入运行列表；退出成功返回登录页。详情页返回列表时保留原分页参数，非法或越权的运行编号统一展示 404 页面。
|
|
|
|
## 4. 页面结构
|
|
|
|
### 4.1 全局布局
|
|
|
|
建立一个全局基础模板，结构包括：
|
|
|
|
- 跳转到主要内容的无障碍链接。
|
|
- 产品名称和主导航。
|
|
- 当前用户标识。
|
|
- 运行列表、个人资料和退出入口。
|
|
- 页面级消息区域。
|
|
- 主内容区域。
|
|
|
|
退出必须使用 POST 表单，不使用可被预加载或误触发的 GET 链接。
|
|
|
|
### 4.2 登录页
|
|
|
|
页面内容：
|
|
|
|
- 用户名输入框。
|
|
- 密码输入框。
|
|
- 登录按钮。
|
|
- 表单级错误和字段级错误。
|
|
|
|
登录失败时不区分“用户不存在”和“密码错误”，避免泄露账户信息。密码字段不得回显。
|
|
|
|
### 4.3 个人资料页
|
|
|
|
字段：
|
|
|
|
- 用户名：只读。
|
|
- 显示名：可编辑。
|
|
- 时区：第一阶段使用受控选择项，默认 `Asia/Shanghai`。
|
|
|
|
提交成功后采用 POST/Redirect/GET，刷新页面不会重复提交。并发更新暂不提供复杂冲突合并，后端仍必须校验当前用户归属。
|
|
|
|
### 4.4 Agent Run 列表页
|
|
|
|
每条记录展示：
|
|
|
|
- 标题或简短运行标识。
|
|
- 当前状态。
|
|
- Agent 名称和版本摘要。
|
|
- 创建、开始和结束时间。
|
|
- 运行耗时。
|
|
- 是否存在待处理人工确认。
|
|
|
|
列表按创建时间倒序分页。第一阶段没有运行记录时展示明确空状态，不显示“创建任务”按钮，避免暗示真实 Agent 功能已开放。
|
|
|
|
### 4.5 Agent Run 详情页
|
|
|
|
页面分为：
|
|
|
|
1. 运行概览：状态、标题、版本、开始和结束时间、用量摘要。
|
|
2. 结果摘要：只展示已脱敏的结构化摘要。
|
|
3. 运行时间线：按事件序号升序展示。
|
|
4. 工具调用：名称、状态、耗时、参数摘要、结果或错误摘要。
|
|
5. 人工确认：只读展示当前状态；第一阶段由 Admin 处理。
|
|
|
|
详情页不展示 API Key、Cookie、密码、完整工具参数或原始模型敏感内容。
|
|
|
|
### 4.6 API 服务商页
|
|
|
|
- 使用服务商卡片目录展示官方直连、国内平台、聚合平台和云平台。
|
|
- 卡片明确区分“仅 API Key”和“需要额外配置”，未完成专用适配的平台不开放保存操作。
|
|
- 配置抽屉只接收 API Key、可选模型标识和是否设为默认服务商；Base URL 与协议由服务端预设。
|
|
- 页面只显示密钥末四位提示，保存后不可读取完整密钥。
|
|
- 连接测试通过后才替换已有配置；失败输入不得破坏原有可用密钥。
|
|
- 搜索与分类使用 GET 查询参数，保存和移除使用 POST、CSRF 与重定向。
|
|
|
|
## 5. 模板复用边界
|
|
|
|
建议模板层级：
|
|
|
|
```text
|
|
templates/
|
|
├── base.html
|
|
├── registration/
|
|
│ └── login.html
|
|
├── accounts/
|
|
│ └── profile.html
|
|
├── agent_runtime/
|
|
│ ├── run_list.html
|
|
│ └── run_detail.html
|
|
└── errors/
|
|
├── 403.html
|
|
├── 404.html
|
|
└── 500.html
|
|
```
|
|
|
|
复用片段仅在存在稳定复用时抽取：
|
|
|
|
- 状态徽标。
|
|
- 分页导航。
|
|
- 表单错误摘要。
|
|
- 时间线事件项。
|
|
|
|
第一阶段不建立通用组件系统，也不为了文件数量提前抽象宏或模板标签库。
|
|
|
|
## 6. 状态与数据所有权
|
|
|
|
服务端拥有所有业务和权限状态，页面不保存跨请求客户端状态。
|
|
|
|
| 状态类型 | 所有者 | 页面行为 |
|
|
| --- | --- | --- |
|
|
| 登录状态 | Django Session | 未登录时跳转登录 |
|
|
| 用户资料 | `accounts` 服务 | GET 回显，POST 校验和保存 |
|
|
| Run 列表与详情 | `agent_runtime` 查询服务 | 仅返回当前用户范围 |
|
|
| 分页状态 | URL 查询参数 | 可复制、可返回 |
|
|
| 表单错误 | Django Form | 同页字段级与全局提示 |
|
|
| 消息反馈 | Django Messages | 重定向后展示一次 |
|
|
|
|
页面只接收格式化后的视图模型，不在模板中执行权限判断、状态转换或复杂数据加工。
|
|
|
|
## 7. 加载、空、错误和权限状态
|
|
|
|
- 服务端页面首屏不引入异步加载骨架。
|
|
- 空列表显示原因和当前阶段说明。
|
|
- 表单校验失败保留非敏感输入并聚焦错误摘要。
|
|
- 资源不存在和跨用户访问统一显示 404。
|
|
- 服务端异常显示通用错误页，并提供返回安全页面的入口。
|
|
- SDK 配置缺失不能阻止登录、资料和历史 Run 查询。
|
|
- 页面不得把后端异常堆栈直接呈现给用户。
|
|
|
|
## 8. 响应式和可访问性
|
|
|
|
- 页面以单列内容为主，在宽屏下限制最大阅读宽度。
|
|
- Run 详情中的宽表格在窄屏改为定义列表或允许局部横向滚动。
|
|
- 所有表单字段必须具有可关联的 `label`、帮助文本和错误描述。
|
|
- 当前导航项提供可感知状态，不只依赖颜色区分。
|
|
- 状态徽标同时包含文本。
|
|
- 焦点样式不可移除，键盘可以访问所有操作。
|
|
- 标题层级连续，每页只有一个主标题。
|
|
- 时间使用语义化 `<time>` 并提供完整时间值。
|
|
|
|
## 9. 安全与隐私
|
|
|
|
- 所有写操作使用 POST 和 CSRF 防护。
|
|
- 登录后重定向参数只允许站内安全地址。
|
|
- 模板启用默认转义，不使用未经审查的 `safe` 输出。
|
|
- 页面只显示脱敏摘要。
|
|
- 不在 URL、HTML 注释或前端脚本中包含密钥和敏感参数。
|
|
- 跨用户访问由查询层限制，模板隐藏按钮不能替代后端权限校验。
|
|
|
|
## 10. 验证清单
|
|
|
|
- 登录成功、登录失败和安全重定向。
|
|
- 未登录访问受保护页面。
|
|
- 个人资料成功保存和校验失败。
|
|
- 两个普通用户之间的资料和 Run 隔离。
|
|
- 运行列表空状态、单页和多页数据。
|
|
- 运行详情事件顺序及敏感字段不展示。
|
|
- 管理员后台访问边界。
|
|
- CSRF 拒绝路径。
|
|
- 键盘导航、焦点、标签和错误关联。
|
|
- 常见桌面和窄屏宽度下的真实浏览器检查。
|
|
|
|
未执行真实浏览器和辅助技术测试前，不得宣称前端交互验收通过。
|
|
|
|
## 11. 待确认项
|
|
|
|
- 产品视觉标识、颜色和字体尚未确定；第一阶段使用简洁系统字体和高对比度基础样式。
|
|
- 是否允许普通用户处理人工确认留到第二阶段决定。
|
|
- 运行列表默认分页大小应在实现时结合样例数据确定。
|
|
- 时区候选范围需在表单实现前明确，不能接受任意未校验字符串。
|