add backend

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

@@ -0,0 +1,668 @@
+# 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 规范说明文档
+