diff --git a/FRONTEND.md b/FRONTEND.md index d3b0587..f20c256 100644 --- a/FRONTEND.md +++ b/FRONTEND.md @@ -1,69 +1,11 @@ # VibeVault 期末大作业报告：前端界面与交互设计 -> 本报告专门用于说明你实现的前端界面与交互设计，建议 800–1500 字。请与 `REPORT.md` 一起提交。 +> 请参考 `FRONTEND_GUIDE.md` 中的写作指导，在此文件中完成你的报告。 +> 建议 800–1500 字。 -## 1. 整体概览与使用流程 +--- -- 简要说明你的前端技术栈（例如：Vite + React + 某 UI 库等），以及项目目录的基本结构。 -- 描述一个典型用户从打开页面到完成核心任务的完整流程，例如： - - 登录 → 查看歌单列表 → 新建歌单 → 向歌单添加歌曲 → 删除歌曲/歌单。 -- 用 2–3 句话概括你的前端设计目标（例如：强调简单易用、突出关键操作、减少页面跳转等）。 + -## 2. 关键界面截图与说明 -请通过 Markdown 语法在本节插入若干张截图（建议 3–6 张），每张截图下方都要有对应说明。示例： -```markdown -![播放列表总览页面](images/playlists-overview.png) -``` - -建议覆盖以下场景（可按实际实现情况调整）： - -1. **播放列表总览页面** - - 标明页面上最重要的区域（例如：导航栏、歌单列表、主要操作按钮）。 - - 说明用户在该界面可以完成哪些操作，这些操作对应了哪些后端 API（如 `GET /api/playlists`、`POST /api/playlists`）。 - -2. **创建/编辑歌单页面或对话框** - - 说明表单字段设计（必填项、可选项）以及你如何做输入校验和错误提示。 - -3. **歌曲列表/详情页面** - - 如有实现，说明歌曲列表如何展示、如何添加/删除歌曲。 - -4. **加载中 / 错误 / 空状态界面** - - 至少展示一种状态；说明你是如何在 UI 层面向用户反馈"正在加载""出现错误""暂无数据"等信息。 - -> 要求：每张截图下方必须有简短文字说明，让不运行代码的读者也能理解界面意图与交互流程。 - -## 3. 组件划分与状态管理 - -- 描述你是如何划分前端组件层次的： - - 哪些是页面级组件？哪些是可复用的通用组件（如按钮、卡片、列表项）？ - - 有无"容器组件 + 展示组件"的区分？ -- 说明状态（state）主要存放在哪里、如何流动： - - 是否使用 React 内部 state、Context、Redux 或其他状态管理方案？ - - 如何避免不必要的重新渲染（如使用 `memo`、拆分组件等）？ -- 如果你有自定义的 hook 或 API 客户端封装，请简单介绍其职责与好处。 - -## 4. 与后端的对接与解耦 - -- 说明你是如何在前端代码中调用后端 API 的： - - 是否集中封装在某个 `api.ts`/`client.ts` 文件？ - - 错误时如何处理（toast 提示、页面错误组件、控制台日志等）？ -- 解释你的环境配置方案： - - 如使用 `.env` 或 Vite 的环境变量，将后端地址抽离为配置，而不是硬编码在组件内。 -- 如有 CORS 或认证（如携带 JWT）的处理，请在此简要说明请求头、拦截器等设计。 - -## 5. 交互细节与用户体验 - -- 列举 2–3 个你刻意设计的交互细节，例如： - - 提交表单前按钮禁用 / loading 状态切换； - - 删除操作前的确认对话框； - - 成功/失败后的反馈提示（toast/snackbar/banner 等）。 -- 说明你在这些设计中考虑的用户体验因素（如误操作防护、反馈及时性、信息层级清晰度等）。 - -## 6. 自我评价与改进思路 - -- 回顾你的前端实现，简要评价： - - 哪些部分你认为完成得比较满意？（例如结构清晰、交互自然等） - - 哪些部分你觉得可以做得更好？（例如视觉设计、响应式布局、性能优化等） -- 如果有更多时间，你会优先在哪些方面改进这个前端界面？为什么？ diff --git a/FRONTEND_GUIDE.md b/FRONTEND_GUIDE.md new file mode 100644 index 0000000..d3b0587 --- /dev/null +++ b/FRONTEND_GUIDE.md @@ -0,0 +1,69 @@ +# VibeVault 期末大作业报告：前端界面与交互设计 + +> 本报告专门用于说明你实现的前端界面与交互设计，建议 800–1500 字。请与 `REPORT.md` 一起提交。 + +## 1. 整体概览与使用流程 + +- 简要说明你的前端技术栈（例如：Vite + React + 某 UI 库等），以及项目目录的基本结构。 +- 描述一个典型用户从打开页面到完成核心任务的完整流程，例如： + - 登录 → 查看歌单列表 → 新建歌单 → 向歌单添加歌曲 → 删除歌曲/歌单。 +- 用 2–3 句话概括你的前端设计目标（例如：强调简单易用、突出关键操作、减少页面跳转等）。 + +## 2. 关键界面截图与说明 + +请通过 Markdown 语法在本节插入若干张截图（建议 3–6 张），每张截图下方都要有对应说明。示例： + +```markdown +![播放列表总览页面](images/playlists-overview.png) +``` + +建议覆盖以下场景（可按实际实现情况调整）： + +1. **播放列表总览页面** + - 标明页面上最重要的区域（例如：导航栏、歌单列表、主要操作按钮）。 + - 说明用户在该界面可以完成哪些操作，这些操作对应了哪些后端 API（如 `GET /api/playlists`、`POST /api/playlists`）。 + +2. **创建/编辑歌单页面或对话框** + - 说明表单字段设计（必填项、可选项）以及你如何做输入校验和错误提示。 + +3. **歌曲列表/详情页面** + - 如有实现，说明歌曲列表如何展示、如何添加/删除歌曲。 + +4. **加载中 / 错误 / 空状态界面** + - 至少展示一种状态；说明你是如何在 UI 层面向用户反馈"正在加载""出现错误""暂无数据"等信息。 + +> 要求：每张截图下方必须有简短文字说明，让不运行代码的读者也能理解界面意图与交互流程。 + +## 3. 组件划分与状态管理 + +- 描述你是如何划分前端组件层次的： + - 哪些是页面级组件？哪些是可复用的通用组件（如按钮、卡片、列表项）？ + - 有无"容器组件 + 展示组件"的区分？ +- 说明状态（state）主要存放在哪里、如何流动： + - 是否使用 React 内部 state、Context、Redux 或其他状态管理方案？ + - 如何避免不必要的重新渲染（如使用 `memo`、拆分组件等）？ +- 如果你有自定义的 hook 或 API 客户端封装，请简单介绍其职责与好处。 + +## 4. 与后端的对接与解耦 + +- 说明你是如何在前端代码中调用后端 API 的： + - 是否集中封装在某个 `api.ts`/`client.ts` 文件？ + - 错误时如何处理（toast 提示、页面错误组件、控制台日志等）？ +- 解释你的环境配置方案： + - 如使用 `.env` 或 Vite 的环境变量，将后端地址抽离为配置，而不是硬编码在组件内。 +- 如有 CORS 或认证（如携带 JWT）的处理，请在此简要说明请求头、拦截器等设计。 + +## 5. 交互细节与用户体验 + +- 列举 2–3 个你刻意设计的交互细节，例如： + - 提交表单前按钮禁用 / loading 状态切换； + - 删除操作前的确认对话框； + - 成功/失败后的反馈提示（toast/snackbar/banner 等）。 +- 说明你在这些设计中考虑的用户体验因素（如误操作防护、反馈及时性、信息层级清晰度等）。 + +## 6. 自我评价与改进思路 + +- 回顾你的前端实现，简要评价： + - 哪些部分你认为完成得比较满意？（例如结构清晰、交互自然等） + - 哪些部分你觉得可以做得更好？（例如视觉设计、响应式布局、性能优化等） +- 如果有更多时间，你会优先在哪些方面改进这个前端界面？为什么？ diff --git a/README.md b/README.md index cda93fc..9261f7d 100644 --- a/README.md +++ b/README.md @@ -144,9 +144,11 @@ ## 四、报告要求（约 20 分） +> 📝 **写作指导**：请参考 `REPORT_GUIDE.md` 和 `FRONTEND_GUIDE.md` 了解详细的写作要求和格式说明。 + ### REPORT.md（10 分） -撰写后端与系统设计报告，建议 1500–3000 字，包括： +在 `REPORT.md` 文件中撰写后端与系统设计报告，建议 1500–3000 字，包括： - 系统架构与数据建模 - 业务逻辑与事务 @@ -157,7 +159,7 @@ ### FRONTEND.md（10 分） -撰写前端界面与交互设计报告，建议 800–1500 字，包括： +在 `FRONTEND.md` 文件中撰写前端界面与交互设计报告，建议 800–1500 字，包括： - 前端技术栈与使用流程 - 关键界面截图与说明（3–6 张） diff --git a/REPORT.md b/REPORT.md index 1cbfe96..72a67c6 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,46 +1,10 @@ # VibeVault 期末大作业报告：后端与系统设计 -> 请使用中文完成报告，建议 1500–3000 字。你可以使用任意 Markdown 编辑工具。 +> 请参考 `REPORT_GUIDE.md` 中的写作指导，在此文件中完成你的报告。 +> 建议 1500–3000 字，使用中文。 -## 1. 系统概览与架构设计 +--- -- 简要描述你的系统功能（例如：歌单管理、歌曲管理、用户管理等）。 -- 画出或文字说明你的分层结构（Controller / Service / Repository），并说明每一层的主要职责。 -- 解释你如何在代码中体现"高内聚、低耦合"和"依赖倒置"。 + -## 2. 数据建模与持久化 -- 描述你的核心实体（如 `User`, `Playlist`, `Song`）及它们之间的关系（如 One-to-Many, Many-to-One）。 -- 解释你选择的主键策略（如 `@GeneratedValue`）和约束（如唯一性、非空约束）的设计理由。 -- 如果你对数据库结构做了扩展或修改，请在此详细说明。 - -## 3. 业务逻辑与事务 - -- 选择 1–2 个你认为最关键的业务用例（例如"批量向歌单添加歌曲并保持原子性"），描述其业务流程。 -- 说明你在这些用例中如何使用事务（如 `@Transactional`），以及这样设计的原因。 -- 如果你实现了高级查询（如模糊搜索、复制歌单），请说明实现方式与性能考虑。 - -## 4. 安全与访问控制 - -- 描述你的认证方案（如 JWT），以及如何将用户身份传递给业务层。 -- 说明你的授权策略：谁可以删除/修改谁的歌单？你是如何在代码中实现"所有权检查"的？ -- 如果你实现了更多安全特性（如密码加密、角色/权限），请在此展开。 - -## 5. 测试策略与质量保障 - -- 概述你为本项目编写的测试类型（单元测试、集成测试等）及覆盖的主要场景。 -- 列举 1–2 个你通过测试发现并修复的典型 bug，说明问题成因和修复思路。 -- 反思：如果以后需要继续扩展本项目，你认为当前的测试体系是否足以支撑频繁重构？为什么？ - -## 6. AI 协同开发反思 - -- 具体描述 2–3 个你在项目中使用大语言模型（如 ChatGPT、Cursor 等）协助开发的案例： - - 你给出了什么样的 Prompt？ - - 得到的回答中哪些部分是直接采用的？哪些部分你进行了修改或重写？ -- 分析：在本项目中，AI 对你最大的帮助是什么？最容易"误导"你的地方又是什么？ -- 总结：你会如何在未来的工程实践中规范、有效地使用 AI 作为编码伙伴？ - -## 7. 总结与自我评估 - -- 总结你在本项目中最重要的三点收获（可以是技术、思维方式或协作方式）。 -- 按照课程要求的大作业评分维度（功能、架构、测试、安全、文档），给自己一个客观的自评分，并简要说明理由。 diff --git a/REPORT_GUIDE.md b/REPORT_GUIDE.md new file mode 100644 index 0000000..1cbfe96 --- /dev/null +++ b/REPORT_GUIDE.md @@ -0,0 +1,46 @@ +# VibeVault 期末大作业报告：后端与系统设计 + +> 请使用中文完成报告，建议 1500–3000 字。你可以使用任意 Markdown 编辑工具。 + +## 1. 系统概览与架构设计 + +- 简要描述你的系统功能（例如：歌单管理、歌曲管理、用户管理等）。 +- 画出或文字说明你的分层结构（Controller / Service / Repository），并说明每一层的主要职责。 +- 解释你如何在代码中体现"高内聚、低耦合"和"依赖倒置"。 + +## 2. 数据建模与持久化 + +- 描述你的核心实体（如 `User`, `Playlist`, `Song`）及它们之间的关系（如 One-to-Many, Many-to-One）。 +- 解释你选择的主键策略（如 `@GeneratedValue`）和约束（如唯一性、非空约束）的设计理由。 +- 如果你对数据库结构做了扩展或修改，请在此详细说明。 + +## 3. 业务逻辑与事务 + +- 选择 1–2 个你认为最关键的业务用例（例如"批量向歌单添加歌曲并保持原子性"），描述其业务流程。 +- 说明你在这些用例中如何使用事务（如 `@Transactional`），以及这样设计的原因。 +- 如果你实现了高级查询（如模糊搜索、复制歌单），请说明实现方式与性能考虑。 + +## 4. 安全与访问控制 + +- 描述你的认证方案（如 JWT），以及如何将用户身份传递给业务层。 +- 说明你的授权策略：谁可以删除/修改谁的歌单？你是如何在代码中实现"所有权检查"的？ +- 如果你实现了更多安全特性（如密码加密、角色/权限），请在此展开。 + +## 5. 测试策略与质量保障 + +- 概述你为本项目编写的测试类型（单元测试、集成测试等）及覆盖的主要场景。 +- 列举 1–2 个你通过测试发现并修复的典型 bug，说明问题成因和修复思路。 +- 反思：如果以后需要继续扩展本项目，你认为当前的测试体系是否足以支撑频繁重构？为什么？ + +## 6. AI 协同开发反思 + +- 具体描述 2–3 个你在项目中使用大语言模型（如 ChatGPT、Cursor 等）协助开发的案例： + - 你给出了什么样的 Prompt？ + - 得到的回答中哪些部分是直接采用的？哪些部分你进行了修改或重写？ +- 分析：在本项目中，AI 对你最大的帮助是什么？最容易"误导"你的地方又是什么？ +- 总结：你会如何在未来的工程实践中规范、有效地使用 AI 作为编码伙伴？ + +## 7. 总结与自我评估 + +- 总结你在本项目中最重要的三点收获（可以是技术、思维方式或协作方式）。 +- 按照课程要求的大作业评分维度（功能、架构、测试、安全、文档），给自己一个客观的自评分，并简要说明理由。