# AIOJ - Online Judge System

基于 Spring Boot 微服务架构的在线判题系统。

## 服务端口配置

| 服务名称 | 端口 | 说明 |
|---------|------|------|
| Gateway | 18085 | API 网关服务 |
| Auth Service | 18081 | 认证授权服务 |
| User Service | 18082 | 用户服务 |
| UPMS | 18083 | 用户权限管理服务 |
| File Service | 18066 | 文件服务 |

## 模块结构

### 核心模块 (aioj-backend-common)

- **aioj-backend-common-bom** - 依赖管理
- **aioj-backend-common-core** - 核心工具类
- **aioj-backend-common-feign** - Feign 客户端配置
- **aioj-backend-common-log** - 日志框架
- **aioj-backend-common-mybatis** - MyBatis 扩展
- **aioj-backend-common-starter** - 自动配置启动器

### 服务模块

- **aioj-backend-gateway** - API 网关
- **aioj-backend-auth** - 认证服务
- **aioj-backend-user-service** - 用户服务
- **aioj-backend-upms** - 权限管理服务
- **aioj-backend-file-service** - 文件服务
- **aioj-backend-judge-service** - 判题服务（开发中）
- **aioj-backend-question-service** - 题库服务（开发中）
- **aioj-backend-ai-service** - AI 服务（开发中）

## 快速开始

### 前置要求

- 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 JAR（Spring 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
# 运行网关
mvn spring-boot:run -pl aioj-backend-gateway

# 运行认证服务
mvn spring-boot:run -pl aioj-backend-auth

# 运行用户服务
mvn spring-boot:run -pl aioj-backend-user-service
```

### 访问地址

- Gateway: http://localhost:18085
- Auth Service: http://localhost:18081/api
- User Service: http://localhost:18082/api
- UPMS: http://localhost:18083/api
- File Service: http://localhost:18066/api

## 常用命令

### 代码格式化

```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`: 构建/工具链相关

## 许可证

[添加许可证信息]

## 联系方式

[添加联系方式]