feat: 添加管理员权限检查功能和Maven打包配置优化

主要更新:

1. 新增管理员权限检查功能
   - 添加 UserRoleEnum 枚举类统一管理用户角色(USER, ADMIN, BAN)
   - 改进 ContextHolderUtils.isAdmin() 方法,支持不区分大小写的角色比较
   - 更新 UserServiceImpl 使用枚举常量代替硬编码字符串
   - 新增管理员权限使用指南文档 (docs/admin-permission-guide.md)

2. 修复Maven打包配置
   - 配置根POM的spring-boot-maven-plugin默认跳过repackage
   - 为所有服务模块启用repackage,确保可以打包为可执行JAR
   - 修复公共库模块打包失败的问题
   - 涉及服务:gateway, auth, user-service, question-service, file-service, blog-service, upms-biz, ai-service

3. 更新项目文档
   - README.md:添加详细的打包说明、首次克隆准备工作、服务启动顺序等
   - CLAUDE.md:更新项目架构说明和开发指南

4. 重构题目服务责任链结构
   - 将责任链类按功能分类到 question/ 和 submit/ 子目录
   - 新增 QuestionSubmitJudgeInfoEnum 和相关查询功能
   - 改进题目提交服务的实现

5. 其他改进
   - 添加 Feign Token 中继拦截器
   - 更新 AsyncConfig 配置
   - 优化 Jackson 和 Security 配置
This commit is contained in:
2026-01-28 23:01:48 +08:00
parent 67825a8c5c
commit 1945cc2fb1
52 changed files with 1561 additions and 89 deletions

291
README.md
View File

@@ -36,13 +36,156 @@
## 快速开始
### 前置要求
- JDK 17 或更高版本
- Maven 3.6 或更高版本
- MySQL 8.0 或更高版本
- Redis 6.0 或更高版本
- Nacos Server 2.x用于服务注册和配置管理
### 首次克隆后的准备工作
1. **克隆项目**
```bash
git clone <repository-url>
cd AI_OJ
```
2. **安装公共依赖模块**
首次克隆后需要先将公共模块安装到本地Maven仓库
```bash
mvn clean install -DskipTests
```
这个命令会:
- 编译所有模块
- 将公共库模块aioj-backend-common-*安装到本地Maven仓库
- 打包所有服务模块为可执行JAR
3. **配置数据库和中间件**
根据各服务的 `application.yml` 配置文件,设置:
- MySQL 数据库连接信息
- Redis 连接信息
- Nacos 服务地址
### 构建项目
```bash
# 编译所有模块(不打包)
mvn clean compile
# 编译并跳过测试
mvn clean compile -DskipTests
```
### 运行服务
## 项目打包
### 打包说明
本项目采用模块化架构,分为**公共库模块**和**服务模块**
- **公共库模块**aioj-backend-common-*编译为普通JAR供其他模块依赖
- **服务模块**打包为包含所有依赖的可执行Fat JARSpring Boot可执行JAR
### 打包所有服务
```bash
# 打包所有服务(推荐)
mvn clean package -DskipTests
# 打包并运行测试
mvn clean package
```
打包完成后,每个服务模块的 `target` 目录下会生成两个JAR文件
- `<service-name>-1.0.0.jar` - 可执行的Fat JAR包含所有依赖约60-100MB
- `<service-name>-1.0.0.jar.original` - 原始JAR仅包含本模块代码约100KB
### 打包单个服务
如果只需要打包某个特定服务:
```bash
# 打包网关服务
mvn clean package -pl aioj-backend-gateway -am -DskipTests
# 打包认证服务
mvn clean package -pl aioj-backend-auth -am -DskipTests
# 打包用户服务
mvn clean package -pl aioj-backend-user-service -am -DskipTests
# 打包题库服务
mvn clean package -pl aioj-backend-question-service -am -DskipTests
# 打包文件服务
mvn clean package -pl aioj-backend-file-service -am -DskipTests
# 打包博客服务
mvn clean package -pl aioj-backend-blog-service -am -DskipTests
# 打包权限管理服务
mvn clean package -pl aioj-backend-upms/aioj-backend-upms-biz -am -DskipTests
```
**参数说明:**
- `-pl <module>`: 指定要构建的模块
- `-am`: 同时构建该模块依赖的其他模块also-make
- `-DskipTests`: 跳过测试
### 打包后的文件位置
打包完成后可执行JAR文件位于各服务模块的 `target` 目录:
```
aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar
aioj-backend-auth/target/aioj-backend-auth-1.0.0.jar
aioj-backend-user-service/target/aioj-backend-user-service-1.0.0.jar
aioj-backend-question-service/target/aioj-backend-question-service-1.0.0.jar
aioj-backend-file-service/target/aioj-backend-file-service-1.0.0.jar
aioj-backend-blog-service/target/aioj-backend-blog-service-1.0.0.jar
aioj-backend-upms/aioj-backend-upms-biz/target/aioj-backend-upms-biz-1.0.0.jar
```
### 运行打包后的服务
使用 `java -jar` 命令运行打包后的服务:
```bash
# 运行网关服务
java -jar aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar
# 运行认证服务
java -jar aioj-backend-auth/target/aioj-backend-auth-1.0.0.jar
# 运行用户服务
java -jar aioj-backend-user-service/target/aioj-backend-user-service-1.0.0.jar
# 指定配置文件运行
java -jar aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar --spring.profiles.active=prod
# 指定JVM参数运行
java -Xms512m -Xmx1024m -jar aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar
```
### 使用Docker部署可选
项目已配置JIB插件可以直接构建Docker镜像
```bash
# 构建Docker镜像到本地
mvn package jib:dockerBuild -pl aioj-backend-gateway -am -DskipTests
# 构建并推送到远程仓库
mvn package jib:build -pl aioj-backend-gateway -am -DskipTests
```
### 开发模式运行
在开发过程中,可以使用 `spring-boot:run` 直接运行服务(无需打包):
```bash
# 运行网关
@@ -68,11 +211,157 @@ mvn spring-boot:run -pl aioj-backend-user-service
### 代码格式化
```bash
# 格式化所有代码
mvn spring-javaformat:apply
# 检查代码格式
mvn spring-javaformat:check
```
### 运行测试
```bash
# 运行所有测试
mvn test
# 运行单个模块的测试
mvn test -pl aioj-backend-user-service
```
### 清理构建产物
```bash
# 清理所有模块的target目录
mvn clean
# 清理单个模块
mvn clean -pl aioj-backend-gateway
```
## 常见问题
### 1. 打包时提示找不到依赖
**问题**:打包服务时提示找不到 `aioj-backend-common-core` 等公共模块。
**解决方案**:首次克隆或更新公共模块后,需要先安装公共模块到本地仓库:
```bash
mvn clean install -DskipTests
```
### 2. 打包失败Unable to find main class
**问题**公共库模块aioj-backend-common-*)打包时报错。
**解决方案**这是正常的公共库模块不应该被打包为可执行JAR。项目已配置为跳过公共模块的repackage。如果遇到此问题请确保使用最新的配置。
### 3. 服务启动失败
**问题**运行JAR时服务无法启动。
**可能原因**
- 数据库连接失败检查MySQL是否启动连接信息是否正确
- Redis连接失败检查Redis是否启动
- Nacos连接失败检查Nacos Server是否启动
- 端口被占用:检查服务端口是否被其他程序占用
**解决方案**:查看日志输出,根据错误信息排查问题。
### 4. 内存不足
**问题**:打包或运行时提示内存不足。
**解决方案**
```bash
# 增加Maven构建内存
export MAVEN_OPTS="-Xmx2048m"
# 或在Windows上
set MAVEN_OPTS=-Xmx2048m
# 运行服务时指定内存
java -Xms512m -Xmx1024m -jar <service>.jar
```
## 服务启动顺序
为确保系统正常运行,建议按以下顺序启动服务:
1. **基础设施服务**(必须先启动)
- MySQL 数据库
- Redis 缓存服务
- Nacos 服务注册中心
2. **核心服务**
- `aioj-backend-auth` - 认证服务(其他服务可能依赖认证)
- `aioj-backend-gateway` - API网关统一入口
3. **业务服务**(可并行启动)
- `aioj-backend-user-service` - 用户服务
- `aioj-backend-upms-biz` - 权限管理服务
- `aioj-backend-question-service` - 题库服务
- `aioj-backend-file-service` - 文件服务
- `aioj-backend-blog-service` - 博客服务
## 技术栈
### 核心框架
- **Spring Boot**: 3.5.7
- **Spring Cloud**: 2025.0.0
- **Spring Cloud Alibaba**: 2025.0.0.0
- **Java**: 17
### 基础设施
- **服务注册与发现**: Alibaba Nacos
- **流量控制**: Alibaba Sentinel
- **API网关**: Spring Cloud Gateway
- **负载均衡**: Spring Cloud LoadBalancer
### 数据存储
- **数据库**: MySQL 8.0
- **ORM框架**: MyBatis
- **缓存**: Redis
- **会话管理**: Spring Session (Redis)
### 安全认证
- **安全框架**: Spring Security
- **认证方式**: JWT (JSON Web Tokens)
### 其他组件
- **对象存储**: 腾讯云COS
- **Markdown解析**: Flexmark
- **API文档**: SpringDoc OpenAPI 3 + Knife4j
- **工具库**: Hutool
## 项目文档
- **[CLAUDE.md](./CLAUDE.md)** - 项目架构和开发指南
- **[管理员权限使用指南](./docs/admin-permission-guide.md)** - 管理员权限检查功能说明
## 开发规范
### 代码风格
- 遵循 Spring Java Format 规范
- 提交前运行 `mvn spring-javaformat:apply` 格式化代码
### 分支管理
- `main` - 主分支,保持稳定
- `develop` - 开发分支
- `feature/*` - 功能分支
- `bugfix/*` - 修复分支
### 提交规范
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具链相关
## 许可证
[添加许可证信息]
## 联系方式
[添加联系方式]