Files

yoyuzh 8db2fa2aab add backend

2026-03-14 11:03:07 +08:00

5.1 KiB

Raw Blame History

# 文件 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 输出：

{
  "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 格式：

{
  "code": 1000,
  "msg": "error message"
}

6. 数据库细则

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

5.1 KiB Raw Blame History Unescape Escape