my_site/草图/pencil-new-前端页面需求文档.md

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 规范说明文档