JobRadar/.craftkit/designs/engineering-baseline/frontend-design.md

reviewStatus, reviewedAt, replacedBy

reviewStatus	reviewedAt	replacedBy
pending	null	null

第一阶段工程基线前端落地设计

1. 文档定位

本文档定义第一阶段 Django 服务端页面的页面结构、路由、交互、状态、权限与可访问性边界。当前项目没有独立前端框架或组件库，因此本阶段使用 Django Templates、Django Forms 和少量原生 CSS，不引入 Vue、React、前端状态库或前后端分离架构。

关联设计：

• 后端落地设计
• 数据库设计
• 接口与页面契约设计
• 第一阶段工程基线开发计划

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. 模板复用边界

建议模板层级：

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. 待确认项

• 产品视觉标识、颜色和字体尚未确定；第一阶段使用简洁系统字体和高对比度基础样式。
• 是否允许普通用户处理人工确认留到第二阶段决定。
• 运行列表默认分页大小应在实现时结合样例数据确定。
• 时区候选范围需在表单实现前明确，不能接受任意未校验字符串。