|
|
# 数学题目生成器 (图形化界面版) 项目说明文档
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1. 项目概述
|
|
|
|
|
|
|
|
|
|
|
|
该项目是一个功能完善的、拥有现代化图形用户界面（GUI）的桌面应用。它旨在为不同年级（小学、初中、高中）的学生提供一个集用户管理、题目练习、自动评分和历史存档于一体的综合性数学学习平台。用户可以通过友好的界面进行注册、登录、选择难度、进行交互式答题，并通过真实的电子邮件接收验证码，确保了账户的安全性。
|
|
|
|
|
|
|
|
|
|
|
|
## 2. 项目功能
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 2.1 用户管理
|
|
|
|
|
|
|
|
|
|
|
|
- **用户注册**：提供邮箱和自定义用户名进行注册。系统会向用户提供的邮箱发送一封包含**真实6位验证码**的邮件，用户需凭此验证码完成注册。
|
|
|
- **密码安全**：支持用户设置符合强度要求（6-10位，含大小写字母和数字）的密码，并在登录状态下安全地修改密码。
|
|
|
- **双模式登录**：系统支持用户使用**邮箱**或**用户名**两种方式配合密码进行登录，更加便捷。
|
|
|
|
|
|
|
|
|
|
|
|
### 2.2 题目与考试
|
|
|
|
|
|
|
|
|
|
|
|
- **智能题目生成**：根据用户选择的年级，动态生成不同复杂度的题目。题目包含2-5个操作数，并能智能地添加有意义的单层或双重括号。
|
|
|
- **交互式答题**：题目以选择题形式在界面中逐题展示，用户可通过鼠标点击进行选择。
|
|
|
- **双向导航**：在答题过程中，用户可以使用“上一题”、“下一题”按钮在题目之间自由切换，检查并修改之前的答案。
|
|
|
- **提前交卷**：用户可在答题未完成时选择提前交卷，系统会进行确认提醒，并根据已完成的题目计分。
|
|
|
- **自动评分与存档**：答题结束后，系统会立即计算得分（百分制）并展示。同时，每一次生成的完整试卷（包含题目、选项、正确答案）都会自动保存到以该用户命名的专属文件夹中，便于后续复习。
|
|
|
|
|
|
|
|
|
|
|
|
### 2.3 用户界面
|
|
|
|
|
|
|
|
|
|
|
|
- **现代化图形界面**：基于 `Java Swing` 和 `FlatLaf` UI库构建，提供了一个美观、清爽、响应流畅的桌面应用体验。
|
|
|
- **多视图切换**：拥有登录、注册、密码设置、主菜单、考试、分数等多个独立视图，流程清晰，操作直观。
|
|
|
- **人性化交互**：答题界面提供实时进度条，导航按钮状态会根据当前题号自动更新，为用户提供清晰的操作指引。
|
|
|
|
|
|
|
|
|
|
|
|
## 3. 系统架构
|
|
|
|
|
|
|
|
|
|
|
|
项目采用业界标准的 **MVC (Model-View-Controller)** 设计模式，确保了代码的高度解耦、可维护性和可扩展性。
|
|
|
|
|
|
|
|
|
|
|
|
### 3.1 模型 (Model)
|
|
|
|
|
|
|
|
|
|
|
|
负责处理数据和业务逻辑，完全独立于界面。
|
|
|
|
|
|
- **`model` 包**: 定义核心数据结构，如 `User`, `Question`。
|
|
|
- **`service` 包**: 实现所有后台服务逻辑，如 `UserManager` (用户管理)、`ExamManager` (考试管理) 和 `EmailService` (邮件发送服务)。
|
|
|
|
|
|
|
|
|
|
|
|
### 3.2 视图 (View)
|
|
|
|
|
|
|
|
|
|
|
|
负责渲染用户界面，是用户直接交互的层面。
|
|
|
|
|
|
- **`view` 包**: 包含了所有的UI界面类，如 `LoginView`, `ExamView`, `MainMenuView` 等。这些类只负责“显示”，不包含任何业务逻辑。
|
|
|
|
|
|
|
|
|
|
|
|
### 3.3 控制器 (Controller)
|
|
|
|
|
|
|
|
|
|
|
|
作为模型和视图之间的桥梁，调度整个应用程序。
|
|
|
|
|
|
- **`controller` 包**: 核心类 `AppController` 在此包中。它接收视图层传来的用户操作，调用模型层处理，并根据结果更新视图层的显示。
|
|
|
|
|
|
|
|
|
|
|
|
## 4. 代码详解
|
|
|
|
|
|
|
|
|
|
|
|
### 4.1 题目生成规则
|
|
|
|
|
|
所有生成器都经过重构，能够生成包含2-5个操作数及有意义括号的复杂表达式。
|
|
|
|
|
|
#### 4.1.1 `PrimaryQuestionGenerator`
|
|
|
|
|
|
为小学用户生成复杂的四则运算题目，智能地使用括号改变运算优先级。
|
|
|
|
|
|
```
|
|
|
((10 + 5) × 3) - 12
|
|
|
```
|
|
|
|
|
|
#### 4.1.2 `JuniorQuestionGenerator`
|
|
|
|
|
|
在复杂表达式中，确保至少包含一个平方 (`^2`) 或开根号 (`√`) 运算。
|
|
|
|
|
|
```
|
|
|
(8 + √ (49)) × 3^2
|
|
|
```
|
|
|
|
|
|
#### 4.1.3 `SeniorQuestionGenerator`
|
|
|
|
|
|
在复杂表达式中，确保至少包含一个三角函数 (`sin`, `cos`, `tan`)，并已修复 `tan(90°)` 的bug。
|
|
|
|
|
|
```
|
|
|
5 × (sin(30°) + 4)
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 4.2 题目格式与计分
|
|
|
|
|
|
- 所有题目均为四选一的选择题。
|
|
|
- 系统会智能判断正确答案是整数还是小数，并生成逻辑相符的干扰选项。
|
|
|
- 计分方式为 `(答对题数 / 总题数) * 100`，结果四舍五入取整。
|
|
|
|
|
|
## 5. 运行说明
|
|
|
|
|
|
|
|
|
|
|
|
1. **启动程序** 运行 `Main.java` 类，启动图形化登录窗口。
|
|
|
2. **用户注册/登录**
|
|
|
- 新用户点击“注册”，按照“输入邮箱/用户名 -> 发送验证邮件 -> 查收邮件验证码 -> 设置密码”的流程完成注册。
|
|
|
- 老用户可使用邮箱或用户名直接登录。
|
|
|
3. **开始考试** 在主菜单选择题目难度和数量，点击“开始答题”进入考试界面。
|
|
|
4. **答题过程** 通过“上一题”、“下一题”进行导航，随时可通过“交卷并评分”按钮结束考试。
|
|
|
5. **查看分数** 交卷后，分数界面会显示本次得分和答题详情。用户可选择“再来一组”或“退出登录”。
|
|
|
|
|
|
|
|
|
|
|
|
## 6. 代码结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
src/
|
|
|
├── Main.java
|
|
|
├── config.properties
|
|
|
├── controller/
|
|
|
│ └── AppController.java
|
|
|
├── model/
|
|
|
│ ├── Question.java
|
|
|
│ ├── User.java
|
|
|
│ └── UserType.java
|
|
|
├── service/
|
|
|
│ ├── EmailService.java
|
|
|
│ ├── ExamManager.java
|
|
|
│ ├── ExpressionEvaluator.java
|
|
|
│ ├── UserManager.java
|
|
|
│ ├── ValidationService.java
|
|
|
│ └── generator/
|
|
|
│ └── ... (5个题目生成器相关文件)
|
|
|
└── view/
|
|
|
└── ... (8个界面视图相关文件)
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 7. 依赖与配置
|
|
|
|
|
|
### 软件依赖 (JAR文件)
|
|
|
|
|
|
本项目需要以下4个外部库文件，以下依赖库以添加至总项目lib文件夹中
|
|
|
|
|
|
- **FlatLaf UI主题**: `flatlaf-3.4.1.jar`
|
|
|
|
|
|
- **Jakarta Mail API**: `jakarta.mail-api-2.1.2.jar`
|
|
|
|
|
|
- **Angus Mail (实现)**: `angus-mail-2.0.2.jar`
|
|
|
|
|
|
- **Angus Activation (依赖)**: `angus-activation-2.0.2.jar`
|
|
|
|
|
|
|
|
|
|
|
|
### Windows 系统下运行步骤
|
|
|
|
|
|
1. **配置 Java 22 编译环境**
|
|
|
|
|
|
确保系统已安装 Java 22 JDK 版本
|
|
|
|
|
|
2. **设置控制台编码**
|
|
|
|
|
|
打开 cmd 命令行工具，使用以下指令执行 .jar 文件：
|
|
|
|
|
|
```
|
|
|
java -jar .\MathExamApp.jar
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Linux 系统下运行步骤
|
|
|
|
|
|
1. **配置 Java 22 JDK 版本**
|
|
|
|
|
|
确保系统已安装 Java 22 JDK
|
|
|
|
|
|
2. **运行程序**
|
|
|
|
|
|
使用以下指令执行程序：
|
|
|
|
|
|
java -jar MathExamApp.jar
|
|
|
|
|
|
|
|
|
|
|
|
## 8. 注意事项
|
|
|
|
|
|
|
|
|
|
|
|
1. **数据文件夹**：程序第一次成功注册用户或生成试卷后，会在程序运行的根目录下自动创建以下文件夹：
|
|
|
- `data/`：此文件夹包含 `users.txt` 文件，用于存储所有用户的账号和密码信息。
|
|
|
- `exams/`：此文件夹下会以每个用户的邮箱/用户名创建子文件夹，用于存放该用户所有历史试卷的 `.txt` 文件。
|
|
|
2. **请勿删除**：上述两个文件夹是程序正常运行和数据持久化的关键。**请不要手动删除或修改这些文件夹及其中的内容**，否则将导致所有用户账号信息和历史试卷记录丢失，且无法恢复。 |
