# classExam

**Repository Path**: henfon/class-exam

## Basic Information

- **Project Name**: classExam
- **Description**: 智慧班级考练管理平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# class-exam 项目说明

## 1. 项目简介

`class-exam` 是一个前后端分离的班级考试与教务管理系统仓库，包含：

- 后端：`class-exam-admin`（Spring Boot 多模块）
- 前端：`class-exam-web`（React + Vite + TypeScript）

当前仓库已经完成菜单权限动态化改造（菜单字典 + 角色授权），并支持班级教师岗位（班主任/科任）变更时的角色联动同步。

## 2. 仓库结构

```text
class-exam/
├── class-exam-admin/                  # 后端工程（Maven 多模块）
│   ├── class-exam-boot/               # 启动模块（Spring Boot 入口、application*.yml）
│   ├── class-exam-common/             # 公共能力（Web/校验/MyBatis-Plus/Redis/Sa-Token 等）
│   ├── class-exam-system/             # 系统管理模块（用户、角色、权限、日志等）
│   ├── class-exam-business/           # 业务模块（班级、考试、题库、设置等）
│   ├── class-exam-ai/                 # AI 能力模块（LangChain4j 接入）
│   └── sql/                           # SQL 脚本（当前提供基础初始化脚本 class-exam.sql）
├── class-exam-web/                    # 前端工程（React + Vite）
└── README.md                          # 当前文档（前后端统一说明）
```

## 3. 后端说明（class-exam-admin）

### 3.1 技术栈（含版本）

后端父 POM：`class-exam-admin/pom.xml`

- Java 17
- Spring Boot `3.2.5`
- MyBatis-Plus `3.5.5`
- Sa-Token `1.37.0`
- Hutool `5.8.26`
- Knife4j OpenAPI3 `4.4.0`
- LangChain4j `1.0.1`（AI 模块）
- MySQL 驱动：`mysql-connector-j`
- Redis：`spring-boot-starter-data-redis`
- 其它关键库：
  - Apache POI `5.2.5`（Excel 导入导出）
  - MinIO Java SDK `8.5.12`（对象存储）
  - Jqwik（属性测试）

### 3.2 本地开发环境要求

- JDK 17（必须）
- Maven 3.8+（建议 3.9+）
- MySQL 8.0+
- Redis 6+（开发环境可选，见下文说明）

### 3.3 配置文件说明

配置目录：`class-exam-admin/class-exam-boot/src/main/resources`

- `application.yml`：公共配置（端口、上下文、Sa-Token、MyBatis-Plus、Knife4j、MinIO、AI）
- `application-dev.yml`：开发环境配置（默认 profile）
- `application-test.yml`：测试环境配置
- `application-prod.yml`：生产环境配置（支持环境变量覆盖）

### 3.4 本地必须修改的配置

#### A. 数据库配置（必须）

文件：`class-exam-admin/class-exam-boot/src/main/resources/application-dev.yml`

必须确认以下配置为你本机实际值：

- `spring.datasource.url`
- `spring.datasource.username`
- `spring.datasource.password`

当前默认库名是 `class-exam`。

示例（按你本机改）：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/class-exam?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: 你的密码
```

#### B. Redis 配置（按需）

同文件中已有 Redis 配置，但 `dev` 环境默认排除了 Redis 自动装配：

```yaml
spring:
  autoconfigure:
    exclude:
      - org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration
      - org.springframework.boot.autoconfigure.data.redis.RedisRepositoriesAutoConfiguration
```

这意味着：

- 开发环境即使不启 Redis，也可通过 `RedisUtils` 的本地内存兜底继续联调。
- 如果你希望开发环境真实使用 Redis，请删除上述 `exclude` 两行并保证 Redis 可连接。

#### C. MinIO 配置（使用上传功能时建议配置）

文件：`application.yml`

配置前缀：`app.minio.*`，支持环境变量覆盖：

- `MINIO_ENDPOINT`
- `MINIO_ACCESS_KEY`
- `MINIO_SECRET_KEY`
- `MINIO_BUCKET`
- `MINIO_PUBLIC_BASE_URL`

推荐配置示例（建议改为你自己的服务地址和密钥）：

```yaml
app:
  minio:
    enabled: true
    endpoint: ${MINIO_ENDPOINT:http://127.0.0.1:9000}
    access-key: ${MINIO_ACCESS_KEY:minioadmin}
    secret-key: ${MINIO_SECRET_KEY:minioadmin}
    bucket: ${MINIO_BUCKET:class-exam}
    public-base-url: ${MINIO_PUBLIC_BASE_URL:http://127.0.0.1:9000}
```

如果你本地暂时不用对象存储，可先设为：

```yaml
app:
  minio:
    enabled: false
```

#### D. AI 配置（使用 AI 功能时必须配置）

文件：`application.yml`

配置前缀：`app.ai.bai-lian.*`

- `enabled`
- `api-key`
- `model`
- `base-url`

推荐配置示例（百炼 / DashScope）：

```yaml
app:
  ai:
    bai-lian:
      enabled: true
      api-key: ${BAILIAN_API_KEY:请替换为你的Key}
      model: ${BAILIAN_MODEL:deepseek-v4-pro}
      base-url: ${BAILIAN_BASE_URL:https://dashscope.aliyuncs.com}
      exam-submit-ai-score-enabled: ${BAILIAN_EXAM_SCORE_ENABLED:false}
```

说明：

- `exam-submit-ai-score-enabled`：是否开启提交后 AI 辅助判分（默认 `false`）。
- 生产环境请务必用环境变量注入密钥，不要把真实 `api-key` 提交到仓库。

建议不要在仓库存放真实密钥，改用环境变量或本地私有配置文件管理。

### 3.5 数据库初始化说明（重要）

当前仓库提供基础初始化脚本：

- `class-exam-admin/sql/class-exam.sql`

执行方式示例：

```bash
mysql -u root -p class-exam < class-exam-admin/sql/class-exam.sql
```

该脚本当前已按“去业务、保留基础配置”精简，主要包含系统表、角色权限表、系统设置表及基础数据。

### 3.6 后端启动步骤

在仓库根目录执行：

```bash
cd class-exam-admin
mvn -pl class-exam-boot spring-boot:run -Dspring-boot.run.profiles=dev
```

启动后默认地址：

- API 根路径：`http://localhost:8080/api`
- Swagger/Knife4j：`http://localhost:8080/api/doc.html`

### 3.7 后端常用命令

```bash
# 编译（跳过测试）
mvn -q -pl class-exam-business -am -DskipTests compile

# 打包
mvn clean package -DskipTests
```

## 4. 前端说明（class-exam-web）

### 4.1 技术栈（含版本）

前端依赖来源：`class-exam-web/package.json`

- Node.js（建议 20 LTS+）
- React `19`
- React Router `7`
- TypeScript `5.8`
- Vite `6.2`
- Tailwind CSS `4.1`
- Lucide React（图标）
- Recharts（图表）
- Socket.IO Client
- 本地开发服务器：Express + Vite Middleware（`server.ts`）

### 4.2 本地开发环境要求

- Node.js 20+（建议）
- npm 10+（或 pnpm）

### 4.3 前端必须关注的配置项

#### A. API 基地址

文件：`class-exam-web/src/api/client.ts`

读取环境变量：

- `VITE_API_BASE`（默认 `/api`）
- `VITE_API_TIMEOUT_MS`（默认 `10000` 毫秒）

默认情况下，前端请求 `/api` 会由本地 `server.ts` 代理到后端：

- 代理目标：`http://127.0.0.1:8080/api`

#### B. 前端开发端口与代理

文件：`class-exam-web/server.ts`

- 当前端口固定为 `3000`
- 如果你要改端口或后端地址，需要修改该文件中的 `PORT` 和 `targetUrl` 逻辑。

#### C. `.env` / `.env.local`

仓库包含 `.env.example`，其中 `GEMINI_API_KEY` 来自模板场景。  
本项目主业务联调主要依赖后端 `/api`，若你不使用相关 AI Studio 模板能力，可先不配置该项。

### 4.4 前端启动步骤

在仓库根目录执行：

```bash
cd class-exam-web
npm install
npm run dev
```

启动后访问：

- 前端页面：`http://localhost:3000`

### 4.5 前端常用命令

```bash
# 类型检查
npx tsc --noEmit

# 构建
npm run build

# 预览构建产物
npm run preview
```

## 5. 前后端联调流程（推荐）

1. 先启动后端（`8080`）
2. 再启动前端（`3000`）
3. 打开 `http://localhost:3000`
4. 前端通过 `server.ts` 自动把 `/api/*` 请求代理到后端 `http://127.0.0.1:8080/api/*`

如果出现 `502 后端服务不可用`，优先检查：

- 后端是否已启动
- 后端端口/上下文路径是否被改动
- `server.ts` 中代理目标是否与后端实际地址一致

## 6. 权限与菜单机制（当前实现）

- 菜单显示不依赖前端写死菜单树
- 后端通过 `/biz/menu/current` 按当前用户角色返回可见菜单
- 菜单字典来源：`ce_system_setting` 的 `menuDictionary`
- 授权关系来源：`ce_role_permission`（`permission_type='menu'` / `data`）

因此新增业务菜单时，一般需要同时做三件事：

1. 前端新增页面并在 `class-exam-web/src/App.tsx` 注册路由
2. 在菜单字典里新增菜单项（含 `id/label/category/path`）
3. 给角色写入对应菜单权限键

## 7. 常见问题

### Q1：前端能打开但接口都报未登录/403？

- 检查本地 token 是否过期（前端会自动清理并跳回登录页）
- 检查后端 `Sa-Token` 配置和用户角色绑定

### Q2：开发环境没启 Redis 会不会启动失败？

默认 `dev` profile 下 Redis 自动配置被排除，可退化为本地缓存，不会因为 Redis 不可用直接阻塞启动。

### Q3：上传/头像功能异常？

优先检查 `app.minio.*` 是否正确配置、MinIO 服务是否可访问、Bucket 是否存在。

---