---
# 文件 1：Yoyuzh_Portal_需求文档.md

# Yoyuzh Personal Portal 后端需求文档

## 项目概述
该项目为 **yoyuzh.xyz** 的后端系统，提供用户身份认证、个人网盘功能以及重庆大学校园信息接口整合，供前端 Vue3 页面调用。

主要功能：
1. 用户身份认证与管理（注册、登录、JWT、密码加密）
2. 个人网盘（文件上传/下载/删除/目录管理/分页列表）
3. 重庆大学校园信息接口（课表、成绩）
4. RESTful API 风格，安全、可扩展

---

## 技术选型
| 模块       | 技术/框架                  | 说明                           |
|------------|---------------------------|--------------------------------|
| 后端框架   | Spring Boot 3.x           | Java RESTful 后端快速开发       |
| 数据库     | MySQL / openGauss         | 用户、文件、课程信息存储       |
| 安全       | Spring Security + JWT     | 身份认证、接口权限控制         |
| 文件存储   | 本地文件系统 / 阿里云 OSS | 网盘文件存储                   |
| 构建工具   | Maven                     | 依赖管理                       |
| API 文档   | Swagger / Springdoc       | 自动生成接口文档               |
| 日志       | SLF4J + Logback           | 日志管理                       |

---

## 功能模块

### 1. 用户身份认证
- 注册：`POST /api/auth/register`，加密密码存储，防止重复用户名/邮箱
- 登录：`POST /api/auth/login`，验证密码并生成 JWT
- JWT 验证：拦截需要权限接口，验证 Token，有效则注入用户信息
- 获取用户信息：`GET /api/user/profile`

### 2. 个人网盘
- 文件上传：`POST /api/files/upload`，文件流 + 路径
- 文件下载：`GET /api/files/download/{fileId}`
- 文件删除：`DELETE /api/files/{fileId}`
- 文件列表：`GET /api/files/list?path=&page=&size=`
- 目录管理：`POST /api/files/mkdir`

### 3. 重庆大学校园信息接口
- 课表查询：`GET /api/cqu/schedule`，学期/学号参数
- 成绩查询：`GET /api/cqu/grades`，学期/学号参数
- 实现：调用现有 API，转换统一 JSON 格式

### 4. 安全与权限
- 网盘接口需登录授权
- 学校信息接口可设置登录访问
- 文件操作需校验用户身份

### 5. 日志与异常
- SLF4J + Logback 日志
- 全局异常处理，统一 JSON 错误返回
- 错误码示例：
  - 1000：未知错误
  - 1001：用户未登录
  - 1002：权限不足
  - 1003：文件不存在

---

## 数据库设计
### 用户表 (user)
```
id PK
username VARCHAR
email VARCHAR
password_hash VARCHAR
created_at DATETIME
```

### 文件表 (file)
```
id PK
user_id FK -> user.id
filename VARCHAR
path VARCHAR
size BIGINT
created_at DATETIME
```

### 课程表 (course)
```
id PK
user_id FK -> user.id
course_name VARCHAR
teacher VARCHAR
classroom VARCHAR
day_of_week INT
start_time INT
end_time INT
```

### 成绩表 (grade)
```
id PK
user_id FK -> user.id
course_name VARCHAR
grade FLOAT
semester VARCHAR
```

---

## 项目结构
```
yoyuzh-portal-backend
│
├─ src/main/java/com/yoyuzh
│   ├─ auth        # 用户注册/登录/JWT
│   ├─ files       # 网盘管理
│   ├─ cqu         # 校园信息 API
│   ├─ common      # 全局异常处理/工具类
│   └─ config      # Spring Security / JWT / Swagger 配置
│
├─ src/main/resources
│   ├─ application.yml  # 数据库/OSS/JWT配置
│   └─ logback.xml      # 日志配置
```

---

# 文件 2：Yoyuzh_Portal_实现细则.md

# Yoyuzh Personal Portal 后端实现细则

## 1. 用户认证细则
- 密码使用 BCrypt 加密存储
- JWT 有效期 1 天，可刷新
- 注册接口验证邮箱和用户名唯一性
- 登录接口返回 Token + 用户基础信息
- 所有需要权限接口通过 JWT Filter 校验
- 异常统一抛出，JSON 返回

## 2. 网盘实现细则
- 上传文件保存路径：`/storage/{userId}/{目录路径}/文件名`
- 文件大小限制：默认 50MB，可在配置文件调整
- 文件列表分页：前端请求 `page` 和 `size`
- 删除文件时先校验用户身份，确保只能删除自己上传的文件
- 支持创建多级目录，目录路径在数据库中记录

## 3. 重庆大学接口细则
- 调用现有 API 获取课表和成绩
- 统一 JSON 输出：
```json
{
  "code": 0,
  "msg": "success",
  "data": [...]
}
```
- 若用户未登录或 Token 无效，可返回 1001 错误码
- 前端可通过学期参数过滤数据

## 4. 安全与权限细则
- Spring Security 配置：
  - `/api/auth/**` 和 Swagger 接口无需认证
  - `/api/files/**` 需要认证
  - `/api/cqu/**` 可选认证
- JWT Token 通过 Authorization Header 传递：`Bearer {token}`

## 5. 日志与异常处理
- 所有接口调用记录 info 日志
- 异常统一在 `@ControllerAdvice` 中处理
- 返回 JSON 格式：
```json
{
  "code": 1000,
  "msg": "error message"
}
```

## 6. 数据库细则
- 用户表：唯一索引 username、email
- 文件表：user_id + path + filename 组合唯一
- 课程表、成绩表与用户表关联，保证查询方便
- 建议为文件表、课程表添加创建时间索引，加快分页查询