final-vibevault-template/README.md

# VibeVault 期末大作业

本大作业要求你在给定的起始代码基础上，完成一个**可运行、可测试、可说明**的 VibeVault 后端系统。

---

## 一、学习目标

- **掌握端到端后端工程能力**：从实体建模、REST API 设计到数据库与事务管理
- **应用三层架构与设计原则**：通过 Controller / Service / Repository 分层
- **构建自动化测试安全网**：使用 JUnit/AssertJ 等工具为核心业务编写测试
- **理解并实现基础安全机制**：落地最小可用的认证与授权骨架
- **学会与 AI 协同开发**：通过高质量 Prompt 使用大模型辅助开发

---

## 二、运行环境

- **JDK 21**
- **Gradle**（使用仓库内 Wrapper：`./gradlew`）
- **Spring Boot 3.4.x**

**本地常用命令**：
```bash
./gradlew test      # 编译与测试
./gradlew bootRun   # 运行应用
```

---

## 三、功能要求

### 🟢 Core 轨道（必做，约 60 分）

#### 1. 实体层（model 包）

完善 `User`、`Playlist`、`Song` 三个 JPA 实体类：

- **User**：用户实体，映射到 `users` 表
  - 用户名必须唯一且不能为空
  - 密码不能为空
  - 包含角色字段（默认 `ROLE_USER`）

- **Playlist**：歌单实体，映射到 `playlists` 表
  - 每个歌单属于一个用户（多对一）
  - 一个歌单包含多首歌曲（一对多）
  - 删除歌单时应级联删除其中的歌曲
  - 实现 `addSong()` 和 `removeSong()` 方法维护双向关系

- **Song**：歌曲实体，映射到 `songs` 表
  - 每首歌曲属于一个歌单（多对一）

#### 2. 仓库层（repository 包）

- **UserRepository**：提供根据用户名查找用户、检查用户名是否存在的方法
- **PlaylistRepository**：继承 JpaRepository 即可

#### 3. 服务层（service 包）

实现 `PlaylistServiceImpl` 中的所有方法：

- 获取所有歌单
- 根据 ID 获取歌单（不存在时抛出 `ResourceNotFoundException`）
- 创建新歌单
- 向歌单添加歌曲
- 从歌单移除歌曲
- 删除歌单

#### 4. 控制器层（controller 包）

**PlaylistController** - 歌单 REST API：

| 端点 | 说明 | 状态码 |
|------|------|--------|
| `GET /api/playlists` | 获取所有歌单 | 200 |
| `GET /api/playlists/{id}` | 获取指定歌单 | 200 / 404 |
| `POST /api/playlists` | 创建新歌单 | 201 |
| `POST /api/playlists/{id}/songs` | 添加歌曲 | 201 |
| `DELETE /api/playlists/{playlistId}/songs/{songId}` | 移除歌曲 | 204 |
| `DELETE /api/playlists/{id}` | 删除歌单 | 204 |

**AuthController** - 认证 API：

| 端点 | 说明 | 状态码 |
|------|------|--------|
| `POST /api/auth/register` | 用户注册 | 201 / 409（用户名已存在） |
| `POST /api/auth/login` | 用户登录 | 200（返回 JWT）/ 401 |

#### 5. 安全配置（security 和 config 包）

- 配置公开接口：`/api/auth/**`、`GET /api/playlists`、`GET /api/playlists/{id}`
- 其他接口需要认证
- 未认证访问受保护资源返回 **401 Unauthorized**
- 实现 JWT 生成、验证和过滤器

---

### 🟡 Advanced 轨道（进阶，约 10 分）

#### 1. 事务与一致性

- 确保 Service 层的写操作都有事务支持
- 批量操作保证原子性

#### 2. 高级查询

在 Repository 和 Service 层添加：

- 按所有者查询歌单
- 按名称模糊搜索歌单
- 复制歌单功能

对应的 Controller 端点：

| 端点 | 说明 |
|------|------|
| `GET /api/playlists/search?keyword=xxx` | 搜索歌单 |
| `POST /api/playlists/{id}/copy?newName=xxx` | 复制歌单 |

#### 3. 统一异常处理

使用 `@RestControllerAdvice` 实现全局异常处理：

- `ResourceNotFoundException` → 404
- `UnauthorizedException` → 403
- 其他异常 → 合适的状态码

---

### 🔴 Challenge 轨道（挑战，约 10 分）

#### 1. 所有权检查

- 只有歌单所有者可以修改/删除自己的歌单
- 非所有者操作他人歌单返回 **403 Forbidden**

#### 2. 角色权限

- 支持用户角色（`ROLE_USER`、`ROLE_ADMIN`）
- 管理员可以删除任何用户的歌单
- 普通用户只能删除自己的歌单

---

## 四、报告要求（约 20 分）

> 📝 **写作指导**：请参考 `REPORT_GUIDE.md` 和 `FRONTEND_GUIDE.md` 了解详细的写作要求和格式说明。

### REPORT.md（10 分）

在 `REPORT.md` 文件中撰写后端与系统设计报告，建议 1500–3000 字，包括：

- 系统架构与数据建模
- 业务逻辑与事务
- 安全与访问控制
- 测试策略与质量保障
- AI 协同开发反思
- 总结与自我评估

### FRONTEND.md（10 分）

在 `FRONTEND.md` 文件中撰写前端界面与交互设计报告，建议 800–1500 字，包括：

- 前端技术栈与使用流程
- 关键界面截图与说明（3–6 张）
- 组件划分与状态管理
- 与后端的对接方式
- 交互细节与用户体验
- 自我评价与改进思路

---

## 五、评分构成

| 项目 | 分值 | 说明 |
|------|------|------|
| Core 测试 | 60 分 | 实体、Service、Controller、基础安全 |
| Advanced 测试 | 10 分 | 事务、高级查询、统一异常处理 |
| Challenge 测试 | 10 分 | 所有权检查、角色权限 |
| REPORT.md | 10 分 | LLM 自动评分 |
| FRONTEND.md | 10 分 | LLM 自动评分 |

> ⚠️ **通过本地公开测试 ≠ 拿满分**。隐藏测试会检查更多边界条件。

---

## 六、提交流程

1. 克隆仓库到本地
2. 完成代码开发
3. 运行 `./gradlew test` 确保公开测试通过
4. 完成 `REPORT.md` 和 `FRONTEND.md`
5. `git add / commit / push` 到 `main` 分支
6. 在 Gitea Actions 页面查看评分结果

---

## 七、学术诚信

- ❌ 禁止直接复制他人代码或报告
- ✅ 允许使用 AI 辅助，但必须**完全理解**生成的代码
- ⚠️ 教师可能通过口头问答或现场演示抽查

---

## 八、建议节奏

- **第 1 周**：完成实体建模（JPA 注解）、Repository、Playlist.addSong/removeSong
- **第 2 周**：完成 Service 层、Controller 层、认证接口
- **第 3 周**：完成 Security 配置、Advanced 和 Challenge 任务
- **截止前**：完成报告，最后一轮自测

---

## 九、代码结构说明

```
src/main/java/com/vibevault/
├── VibeVaultApplication.java    # 启动类（已完成）
├── config/
│   └── SecurityConfig.java      # 安全配置（待实现）
├── controller/
│   ├── AuthController.java      # 认证控制器（待实现）
│   └── PlaylistController.java  # 歌单控制器（待实现）
├── dto/
│   ├── PlaylistDTO.java         # 歌单响应 DTO（已完成）
│   ├── PlaylistCreateDTO.java   # 创建歌单请求 DTO（已完成）
│   ├── SongDTO.java             # 歌曲响应 DTO（已完成）
│   └── SongCreateDTO.java       # 添加歌曲请求 DTO（已完成）
├── exception/
│   ├── GlobalExceptionHandler.java    # 全局异常处理（待实现）
│   ├── ResourceNotFoundException.java # 资源不存在异常（已完成）
│   └── UnauthorizedException.java     # 未授权异常（已完成）
├── model/
│   ├── User.java                # 用户实体（待添加 JPA 注解）
│   ├── Playlist.java            # 歌单实体（待添加 JPA 注解）
│   └── Song.java                # 歌曲实体（待添加 JPA 注解）
├── repository/
│   ├── UserRepository.java      # 用户仓库（待添加查询方法）
│   └── PlaylistRepository.java  # 歌单仓库（待添加查询方法）
├── security/
│   ├── JwtService.java          # JWT 服务（待实现）
│   └── JwtAuthenticationFilter.java  # JWT 过滤器（待实现）
└── service/
    ├── PlaylistService.java     # 歌单服务接口（已完成）
    └── PlaylistServiceImpl.java # 歌单服务实现（待实现）
```

祝你顺利完成！记住：**理解永远比"跑通一次"更重要。**