# Personal Portal 前端页面需求文档

## 1. 文档说明

- 设计来源：`草图/pencil-new.pen`
- 目标：将设计稿整理为可执行的前端页面需求，供 UI 开发、接口联调、测试验收使用
- 适用范围：PC Web 端个人门户站点
- 设计基准尺寸：`1440 x 1024`
- 说明：文档中未在设计稿中直接标注但对实现必需的内容，已按常规门户产品逻辑做合理补充，并明确写为“建议”或“推断”

## 2. 产品定位

这是一个统一个人门户站点，用于集中承载以下能力：

- 账号登录
- 首页总览
- 网盘文件管理
- 教务数据查询
- 游戏入口聚合

站点风格偏深色、毛玻璃、卡片式信息展示，强调“统一入口”和“个人数据聚合”。

## 3. 站点信息架构

建议前端按以下一级路由组织：

| 页面 | 建议路由 | 页面目标 |
| --- | --- | --- |
| 登录页 | `/login` | 完成身份认证并进入门户 |
| 总览页 | `/overview` | 汇总展示用户、文件、课程、成绩等核心信息 |
| 网盘页 | `/files` | 浏览、筛选、查看和上传个人文件 |
| 教务页 | `/school` | 查询课表、成绩并展示学期数据 |
| 游戏页 | `/games` | 提供小游戏入口和分类切换 |

## 4. 全局设计与交互要求

### 4.1 全局视觉规范

- 页面主背景为深蓝黑色系，建议主背景色接近 `#07101D`
- 卡片、导航、输入框采用半透明深色背景叠加模糊效果，形成毛玻璃风格
- 主强调色为亮蓝色，建议主色接近 `#336EFF`
- 文字颜色分三级：
  - 一级文字：高亮白色，用于标题、主按钮文字、关键数据
  - 二级文字：浅蓝灰色，用于说明文案、次要导航
  - 三级文字：更浅的透明文字，用于分隔说明和弱提示
- 整站圆角统一偏大，按钮、卡片、胶囊标签均使用较高圆角

### 4.2 全局布局要求

- 所有页面采用顶部导航 + 主内容区结构
- 顶部导航固定在页面顶部，默认包含站点品牌和一级导航入口
- 主内容区使用卡片化分区布局，不同页面根据业务类型使用多列或多卡片排布
- 所有卡片之间需要保留清晰的间距层级，避免信息拥挤

### 4.3 全局导航要求

- 顶部左侧固定展示站点品牌：
  - 主标题：`YOYUZH.XYZ`
  - 副标题：`Personal Portal`
- 顶部右侧固定展示一级导航：
  - 总览
  - 网盘
  - 教务
  - 游戏
- 当前所在页面的导航项为激活态：
  - 高亮蓝色背景
  - 白色文字
  - 带轻微发光或阴影
- 非当前页面为普通态：
  - 半透明深色背景
  - 浅色文字
- 点击一级导航后执行页面切换，建议保留当前登录态

### 4.4 全局交互要求

- 所有按钮、胶囊标签、切换项、列表行都应具备 hover、focus、active 状态
- 键盘 Tab 顺序必须与视觉顺序一致
- 图标型按钮若后续补充图标，必须提供 `aria-label`
- 卡片内部若有按钮组，主操作需突出显示，次操作保持弱化视觉
- 页面切换过程中应有最基本的加载保护，避免空白闪烁

### 4.5 全局状态要求

每个业务页面至少支持以下状态：

- 加载中：显示骨架屏或占位态
- 加载成功：展示设计稿对应内容
- 空状态：当列表、课表、成绩无数据时显示空态说明
- 错误状态：接口失败时显示错误提示与重试入口
- 未登录状态：除登录页外，若无有效登录态应跳回登录页

### 4.6 响应式要求

设计稿是桌面端稿件，前端实现时建议补齐以下断点：

- `>= 1280px`：按设计稿布局展示
- `768px - 1279px`：多列卡片可改为 2 列，右侧预览或抽屉可下移
- `< 768px`：顶部导航压缩为可滚动标签或抽屉菜单；卡片全部改为单列堆叠

移动端适配要求：

- 不允许出现横向滚动条
- 卡片内文字不可溢出遮挡
- 按钮点击热区不小于 `44 x 44px`
- 文件表格在小屏下可切换为列表卡片模式

### 4.7 可访问性要求

- 文本与背景对比度满足基本可读性
- 表单字段必须带标签
- 所有可点击控件需支持键盘操作
- 当前导航项、当前分段切换项需要有明确的选中态
- 动画需兼容 `prefers-reduced-motion`

## 5. 登录页需求

### 5.1 页面目标

为用户提供统一入口，完成账号认证并进入门户首页。

### 5.2 页面结构

页面分为左右两区：

- 左侧品牌介绍区
- 右侧登录表单区

### 5.3 左侧品牌介绍区

应包含以下元素：

- 品牌标题：`YOYUZH.XYZ`
- 品牌副标题：`Personal Portal`
- 胶囊标签：`Access Portal`
- 主标题：`个人网站统一入口`
- 一段站点简介文案

实现要求：

- 左侧内容垂直排列，整体偏页面左上区域
- 背景需要有大面积柔和发光装饰，营造氛围感
- 简介文案允许后续替换为真实站点介绍

### 5.4 右侧登录表单区

表单卡片应包含以下字段和元素：

- 表单标题：`登录`
- 用户名输入框
- 密码输入框
- 主按钮：`进入系统`

字段要求：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| 用户名 | 文本输入 | 是 | 支持账号、用户名或学号 |
| 密码 | 密码输入 | 是 | 采用掩码显示 |

交互要求：

- 用户名、密码均为空时点击按钮，给出必填校验
- 支持按 Enter 提交表单
- 登录请求发起后按钮进入 loading 状态并禁用重复点击
- 登录成功后跳转至 `/overview`
- 登录失败时在表单区域显示错误提示

建议补充能力：

- 记住登录状态
- 登录态过期自动跳转登录页
- 允许后续增加验证码或二次验证

### 5.5 登录页验收标准

- 页面首屏能清晰表达“统一入口”的产品定位
- 输入框、按钮在视觉上与整体毛玻璃风格统一
- 表单校验、提交、错误反馈完整
- 登录成功跳转逻辑正常

## 6. 总览页需求

### 6.1 页面目标

集中展示用户最常用的跨模块摘要信息，让用户在一个页面看到文件、课程、成绩、账号等核心状态。

### 6.2 页面结构

总览页包含以下模块：

- 顶部导航栏
- 欢迎 Hero 区
- 4 张数据指标卡片
- 最近文件卡片
- 今日 / 本周课程卡片
- 快捷操作卡片
- 存储空间卡片
- 账号信息卡片

### 6.3 Hero 欢迎区

需展示以下内容：

- 欢迎语：如 `欢迎回来，tester5595`
- 当前时间与问候语：如 `现在时间 20:17 · 晚上好`
- 简短页面说明

实现要求：

- 欢迎语作为页面最强视觉标题
- 当前时间应来自前端运行时或服务端返回，不应硬编码
- 问候语应根据时间段变化，建议分为凌晨、早上、下午、晚上

### 6.4 指标卡片区

共 4 个指标模块：

| 模块 | 示例值 | 说明 |
| --- | --- | --- |
| 网盘文件总数 | `128` | 展示文件总量及分类说明 |
| 最近 7 天上传 | `6` | 展示近 7 日上传数量和最近更新时间 |
| 本周课程 | `18` | 展示本周课程总量及今日课节数 |
| 已录入成绩 | `42` | 展示成绩总数及最近学期 |

实现要求：

- 数字需突出显示
- 标题、数字、补充描述分层明显
- 支持接口数据为空时展示 `0` 和空说明

### 6.5 最近文件模块

需展示：

- 模块标题：`最近文件`
- 最近文件列表，建议至少显示 3 条
- 每条信息至少包含：
  - 文件名
  - 文件大小
  - 最近更新时间

交互要求：

- 点击文件项可跳转 `/files`，并定位到该文件
- 文件名超长时需截断并保留 tooltip 或完整展示方案

### 6.6 课程模块

模块标题：`今日 / 本周课程`

模块内包含：

- 分段切换：`今日` / `本周`
- 课程列表，建议显示：
  - 时间段
  - 课程名称
  - 教室或地点

交互要求：

- 默认选中 `今日`
- 点击 `本周` 后刷新为本周课表摘要
- 切换过程不可造成卡片高度明显抖动

### 6.7 快捷操作模块

需提供 4 个快捷入口：

- 上传文件
- 新建文件夹
- 进入网盘
- 查询成绩

交互要求：

- 上传文件：打开上传弹窗或跳转文件页并打开上传面板
- 新建文件夹：打开新建文件夹表单
- 进入网盘：跳转 `/files`
- 查询成绩：跳转 `/school` 并聚焦成绩查询区域

### 6.8 存储空间模块

需展示：

- 模块标题：`存储空间`
- 已使用容量 / 总容量，如 `12.6 GB / 50 GB`
- 使用进度条
- 百分比数值，如 `25%`

实现要求：

- 进度条宽度与百分比联动
- 数值格式统一保留 1 位小数或按产品约定显示

### 6.9 账号信息模块

需展示：

- 模块标题：`账号信息`
- 用户名
- 邮箱

建议补充：

- 后续预留头像、绑定状态、退出登录入口

### 6.10 总览页验收标准

- 各卡片数据层级清晰，首屏即可理解
- 快捷操作能通往对应模块
- 时间、课表、文件、容量信息均支持动态数据渲染
- 页面在 1280px 以上布局稳定，在平板和移动端能正常堆叠

## 7. 网盘页需求

### 7.1 页面目标

提供个人网盘文件浏览、路径导航、详情预览和基础操作入口。

### 7.2 页面结构

网盘页采用三栏布局：

- 左侧目录导航栏
- 中间文件内容区
- 右侧详细信息预览栏

### 7.3 左侧目录导航栏

建议包括两组内容：

- 快速访问
  - 桌面
  - 下载
  - 文档
  - 图片
- 网盘目录
  - 我的文件
  - 课程资料
  - 项目归档
  - 收藏夹

交互要求：

- 点击目录项刷新中间内容区
- 当前目录项应有激活态
- 若目录层级增加，建议支持树形展开

### 7.4 中间文件内容区

应包含以下元素：

- 路径面包屑栏
- 视图切换控件：`列表` / `分栏` / `预览`
- 文件列表表头
- 文件列表内容
- 底部操作按钮：`新建`、`上传`

面包屑要求：

- 当前示例路径为：`网盘 > 我的文件 > 课程资料 > 软件工程`
- 每一级路径应可点击返回

文件列表字段要求：

| 列名 | 说明 |
| --- | --- |
| 名称 | 文件或文件夹名称 |
| 修改日期 | 最近更新时间 |
| 类型 | 文件类型或目录类型 |
| 大小 | 文件大小；文件夹可显示 `—` |

列表交互要求：

- 支持单行选中
- 支持文件夹进入下一级目录
- 支持当前选中项同步到右侧详情栏
- 当前选中行需有明显高亮
- 文件名过长时截断处理

建议补充能力：

- 双击打开文件
- 右键菜单
- 多选
- 排序
- 搜索

### 7.5 右侧详细信息预览栏

需展示当前选中文件的详细信息：

- 当前选择的文件名
- 文件路径
- 文件大小
- 上传时间

建议扩展字段：

- 文件类型图标
- 最近编辑人
- 下载次数
- 预览缩略图

### 7.6 网盘页操作要求

主操作：

- 上传
- 新建

交互说明：

- 上传：支持本地文件选择，建议支持拖拽上传
- 新建：默认创建文件夹，也可为后续扩展新建文档保留能力
- 操作成功后，文件列表与统计信息应刷新

### 7.7 网盘页状态要求

- 空目录：显示空状态文案和“上传文件”入口
- 加载中：文件表格骨架屏
- 上传中：显示上传进度
- 上传失败：显示失败原因并支持重试

### 7.8 网盘页验收标准

- 三栏布局信息职责明确
- 面包屑、目录树、列表选中、右侧详情联动正常
- 上传与新建入口位置明显，交互闭环完整
- 小屏情况下可退化为“目录 / 列表 / 详情”分步展示

## 8. 教务页需求

### 8.1 页面目标

提供统一教务查询入口，用于查看课表、成绩及历史学期数据摘要。

### 8.2 页面结构

页面包含以下主要区域：

- 教务查询卡片
- 数据摘要卡片
- 课表抽屉卡片
- 成绩热力图区域

### 8.3 教务查询卡片

应包含以下字段：

| 字段 | 示例 | 说明 |
| --- | --- | --- |
| 学号 | `2023123456` | 查询账号 |
| 密码 | `••••••••` | 教务系统密码 |
| 学期 | `2025 秋` | 当前选择学期 |

按钮包括：

- 查询课表
- 查询成绩

交互要求：

- 学号、密码、学期为必填项
- 点击 `查询课表` 后刷新课表抽屉和摘要区对应信息
- 点击 `查询成绩` 后刷新成绩区域和摘要区对应信息
- 建议保留上次成功查询的账号与学期缓存

### 8.4 数据摘要卡片

需展示缓存或最近一次查询结果摘要：

- 当前缓存账号
- 已保存课表学期
- 已保存成绩学期列表

实现要求：

- 未查询时显示空态说明
- 查询成功后即时更新

### 8.5 课表抽屉卡片

模块标题：`课表抽屉`

展示形式：

- 按星期分组展示课程
- 每条课程至少包含：
  - 上课时间
  - 课程名称
  - 教室

交互要求：

- 右侧有明显的抽屉把手视觉提示
- 建议支持展开 / 收起或横向滑出效果
- 抽屉在平板和移动端可切为底部弹层

### 8.6 成绩视图切换

查询卡片内存在分段切换：

- 课表
- 成绩

要求：

- 默认激活 `课表`
- 切换到 `成绩` 时，页面焦点应转向成绩区域
- 当前激活项需具备明显视觉反馈

### 8.7 成绩热力图区域

模块标题：`成绩热力图`

需展示多个学期的成绩分布示意，设计稿中包含：

- `2024 秋`
- `2025 春`
- `2025 秋`

实现要求：

- 每个学期形成独立列
- 每列包含多个课程成绩条
- 颜色深浅或透明度表示成绩高低
- 条形右侧或内部显示分数

建议补充能力：

- 悬浮提示课程名、学分、绩点
- 学期筛选
- 按成绩排序

### 8.8 教务页状态要求

- 未查询：显示引导说明
- 查询中：按钮 loading，结果区骨架屏
- 查询成功：更新课表、摘要、成绩
- 查询失败：展示错误原因和重试入口

### 8.9 教务页验收标准

- 查询表单、结果摘要、课表和成绩之间联动清晰
- 抽屉与热力图区域在不同状态下布局稳定
- 历史学期成绩能正确映射为视觉强弱差异

## 9. 游戏页需求

### 9.1 页面目标

作为轻量娱乐入口页，承载站内小游戏展示和启动入口。

### 9.2 页面结构

页面包含：

- 顶部导航
- 页面说明 Hero 区
- 分类切换
- 游戏卡片列表

### 9.3 Hero 区

需展示：

- 模块标题：`游戏入口`
- 一段说明文案，表达“保留轻量试玩与静态资源检查入口，维持与整站一致的毛玻璃语言”

### 9.4 分类切换

设计稿中包含：

- 精选
- 全部

交互要求：

- 默认选中 `精选`
- 点击后刷新卡片列表
- 若当前仅有少量游戏，`全部` 可与 `精选` 数据一致

### 9.5 游戏卡片

设计稿中至少包含两个游戏入口：

| 名称 | 描述 | 按钮文案 |
| --- | --- | --- |
| CAT | 简单的小猫升级游戏 | Launch |
| RACE | 赛车休闲小游戏 | Launch |

交互要求：

- 点击 `Launch` 后进入游戏详情页、游戏运行页或新窗口
- 游戏卡片需支持封面图扩展位
- 后续支持增加更多游戏时，卡片布局可扩展

### 9.6 游戏页验收标准

- 卡片入口清晰，用户能快速理解每个游戏内容
- 分类切换有效
- 启动按钮行为明确，不产生死链

## 10. 数据与接口需求建议

### 10.1 登录相关

- 登录接口：提交用户名和密码，返回用户信息与 token
- 获取当前登录用户接口：用于页面初始化恢复登录态

### 10.2 总览相关

- 获取总览统计接口
- 获取最近文件接口
- 获取今日 / 本周课表摘要接口
- 获取账号信息接口
- 获取存储容量接口

### 10.3 网盘相关

- 获取目录树接口
- 获取当前路径文件列表接口
- 获取文件详情接口
- 上传文件接口
- 新建文件夹接口

### 10.4 教务相关

- 查询课表接口
- 查询成绩接口
- 获取历史查询缓存接口

### 10.5 游戏相关

- 获取游戏列表接口
- 获取游戏分类接口

## 11. 前端实现建议

- 建议将顶部导航抽为全局公共组件
- 建议将卡片、按钮、分段切换、信息列表抽为复用组件
- 建议为每个页面单独维护数据请求与状态管理
- 建议所有动态时间、容量、数量、成绩统一做格式化封装
- 建议页面首屏背景光斑与毛玻璃效果使用纯 CSS 或轻量方案实现，避免过重图像资源

## 12. 测试验收清单

- 登录页表单校验、错误提示、提交跳转正常
- 顶部导航在 5 个页面间切换正常，当前态正确
- 总览页卡片数据渲染与快捷跳转正常
- 网盘页目录、路径、列表、详情联动正常
- 教务页查询、切换、热力图展示正常
- 游戏页分类切换和启动行为正常
- 页面在桌面、平板、移动端无明显布局错乱
- 页面无横向滚动，文本无明显遮挡
- 键盘可访问性与 focus 状态正常

## 13. 交付物建议

前端开发阶段建议同步产出以下内容：

- 页面路由结构
- 公共布局组件
- 各页面接口类型定义
- 空状态、错误状态、加载状态组件
- 基础 UI 规范说明文档