183 lines
5.1 KiB
Markdown
183 lines
5.1 KiB
Markdown
---
|
||
# 文件 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 组合唯一
|
||
- 课程表、成绩表与用户表关联，保证查询方便
|
||
- 建议为文件表、课程表添加创建时间索引，加快分页查询
|
||
|