# 数学题目生成器 (图形化界面版) 项目说明文档





## 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. **请勿删除**：上述两个文件夹是程序正常运行和数据持久化的关键。**请不要手动删除或修改这些文件夹及其中的内容**，否则将导致所有用户账号信息和历史试卷记录丢失，且无法恢复。