669 lines
17 KiB
Markdown
669 lines
17 KiB
Markdown
# 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 规范说明文档
|
||
|