add backend

需求文档.md

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