AUBB 文档中心

Appearance

前端设计规范 ​

1. 设计目标 ​

AUBB 前端是教学、实验和治理工作台，不是营销站点。界面应优先服务高频操作、长表单录入、表格筛选、批量处理、提交查看和批改反馈。

  • 清晰：页面进入后直接呈现当前角色的核心任务、当前范围和下一步操作。
  • 高效：减少重复跳转和层层嵌套，常用动作放在稳定位置。
  • 克制：避免装饰性大图、英雄区、堆叠卡片和大面积说明文字。
  • 可信：权限、保存、提交、发布、重判、导出等状态必须有明确反馈。

2. 应用框架 ​

2.1 顶栏 ​

  • 高度 64px，承载全局搜索、通知、用户菜单、工作区切换和必要的全局命令。
  • 同一用户可同时拥有学生、教师、助教、管理员身份；顶栏必须提供工作区切换，并记住上次选择。
  • 顶栏不放页面内筛选和批量操作。页面级操作进入页面工具栏。

2.2 侧边栏 ​

  • 展开宽度 240px，收起宽度 56px。
  • 必须支持收起 / 展开；收起时保留图标、选中态和 tooltip。
  • 一级导航按工作区组织：管理员、教师/助教、学生。
  • 课程详情、作业、题库、判题环境、成绩等上下文导航优先使用二级侧栏或页内 tabs；三级以下入口用下拉菜单或分组列表收敛。

2.3 页面工具栏 ​

  • 页面标题下方或右侧放置页面主操作、筛选、刷新、导出、批量操作和返回入口。
  • 主操作最多一个，使用实心按钮；次要操作使用描边或菜单。
  • 批量操作必须在选中数据后出现或启用，避免默认占据页面主视觉。

2.4 内容区 ​

  • 常规最大宽度 1440px；数据表、IDE、成绩册等工作台页面可使用全宽。
  • 桌面优先，主要验收视口为 1440x900 和 1280x800。
  • 本阶段不做移动端专项验收；小屏只要求不出现影响桌面设计的结构性问题。

3. 页面结构 ​

3.1 列表页 ​

  • 顶部：标题、范围说明、主操作。
  • 筛选区：搜索、状态、课程/班级、时间等筛选项保持一行优先，复杂筛选放“更多筛选”。
  • 主体：表格优先。列宽稳定，行操作固定在右侧。
  • 空态：说明为什么为空，并提供一个可执行操作或返回路径。

3.2 详情页 ​

  • 顶部显示对象名称、状态、更新时间和主要操作。
  • 主体采用“摘要栏 + 分区内容 + 关联列表”。
  • 不使用卡片套卡片。需要区分信息时，用分区标题、边框、间距和状态标签。
  • 危险操作放在次级菜单或独立危险区，不和主操作混在一起。

3.3 表单页 ​

  • 长表单按业务步骤或分组组织：基础信息、范围、规则、内容、确认。
  • 字段 label 使用业务语言，不直接暴露 orgUnitId、actorUserId、judgeConfig JSON 等技术名。
  • 错误应显示在字段旁；跨字段错误显示在表单顶部错误区。
  • 保存草稿、发布、重新发布、提交等动作必须文案明确，不能只写“确定”。

3.4 工作台页 ​

适用于 WebIDE、成绩册、提交详情、批改页。

  • 工作台优先稳定布局，不因内容加载、hover、错误提示改变主要区域尺寸。
  • 左侧为导航或对象列表，中间为主工作区，右侧为属性、结果或历史记录。
  • 所有可恢复动作必须提供最近保存时间、失败提示和重试入口。

4. 视觉与组件 ​

4.1 色彩 ​

  • 主色使用品牌蓝：oklch(55% 0.22 260)。
  • 成功、警告、危险分别使用绿色、琥珀色、红色，不用蓝色替代所有状态。
  • 页面底色保持浅灰，内容面板保持白色；避免全站只由蓝色、灰色和深色组成。
  • 状态颜色必须配合文字或图标，不只依赖颜色表达含义。

4.2 字体与密度 ​

  • 页面标题约 30px，分区标题约 20px，正文 14px 到 16px。
  • 表格、筛选区、工具栏使用紧凑密度；教学说明和 Markdown 内容使用更舒展行高。
  • 不使用随视口宽度缩放的字体；字间距保持 0。

4.3 按钮 ​

  • 常规高度 36px 到 40px，圆角 6px。
  • 工具类按钮优先使用 lucide 图标，并提供 tooltip。
  • 只有明确命令使用文字按钮；保存、发布、导出、重判、提交等高风险动作必须可读。

4.4 表格 ​

  • 表格必须支持加载态、空态、错误态、分页和行级权限裁剪。
  • 长文本默认截断并提供 tooltip 或详情入口。
  • 行操作不超过三个；更多操作进入菜单。
  • 批量导入、导出、停用、转班等操作必须有确认和结果摘要。

4.5 Dialog、Drawer 与 Tabs ​

  • 简短确认使用 Dialog。
  • 复杂编辑、长表单和详情预览优先使用 Drawer 或独立页面。
  • Tabs 用于同一对象下的同级内容，不用于隐藏主流程步骤。

4.6 状态反馈 ​

  • 加载：骨架屏或局部 spinner，不能让页面跳动。
  • 成功：短提示 + 数据刷新或局部回写。
  • 失败：显示原因、影响范围和重试入口。
  • 403：页面或操作位置必须显示权限不足原因，不能只依赖控制台。
  • 乐观更新失败：必须回滚本地状态，或明确标记“未同步”。

5. 教学内容 ​

作业题目描述、实验内容、公告、资源说明等说明性正文支持 Markdown；资源说明在上传、编辑和师生资源列表中都应保持一致口径。

  • 支持标题、列表、引用、表格、代码块、行内代码、链接和附件引用。
  • 正文阅读宽度建议 72ch 到 88ch；代码块和表格可横向滚动。
  • Markdown 内容不放进窄卡片，不用灰色小字承载主要教学要求。
  • Markdown 阅读区统一走安全渲染组件；默认不解析原始 HTML，只允许安全链接协议，避免脚本标签或事件属性进入 DOM。

6. WebIDE ​

WebIDE 参考 GitLab Web IDE 和 VS Code 的工作台体验。

  • 布局包含文件树、编辑器、多标签、运行结果、版本历史和状态栏。
  • 不提供终端；仅提供标准输入框、运行按钮、样例选择和输出面板。
  • IDE 内“提交”语义等同于保存当前编程题并返回作业界面。
  • 整份结构化作业的正式提交只能在作业详情页完成。
  • 多文件禁用时隐藏或禁用新建文件 / 目录入口。
  • 后端拒绝文件操作时，前端必须回滚文件树并显示错误。

7. 验收检查 ​

前端页面进入验收前，应至少检查：

  • 1280x800 下标题、筛选、主操作、表格行操作不重叠。
  • 页面没有卡片套卡片或无意义的大段说明。
  • 主要按钮文案能区分保存、提交、发布、重新发布、重判和导出。
  • 表格和表单具备加载、空态、错误、无权限状态。
  • 技术字段没有直接暴露给普通用户。
  • WebIDE、成绩册、批改页等工作台布局稳定，不因动态内容明显跳动。

8. 技术实现 ​

  • Framework：Next.js 16 App Router。
  • Styling：Tailwind CSS 4。
  • Components：shadcn/ui。
  • Icons：lucide-react，保持统一线宽。
  • Editor：Monaco Editor。
  • Animation：150ms 到 300ms，避免夸张动效。