hnu202326010308
/
wys_dcx_double_proj
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Labels Milestones
New Pull Request

第三次合并 #3

Merged
hnu202326010308 merged 1 commits from develop into main 6 months ago
Conversation 0 Commits 1 Files Changed 1
1 changed files with 330 additions and 329 deletions
Show Stats Download Patch File Download Diff File

659
doc/README.md
Unescape View File

@ -1,330 +1,331 @@
# 数学学习软件 - 详细说明文档
## 一、项目简介
本项目是一款面向小学、初中和高中学生的数学学习软件，通过图形化界面提供个性化的数学题目生成与练习功能。系统支持用户注册登录、密码管理、年级选择、题目生成、答题练习和成绩展示等功能，所有数据均通过文件系统存储，无需额外的数据库支持。
## 二、功能特点
1. **用户注册与登录**：支持邮箱注册（包含验证码验证），支持用户名或邮箱登录
2. **密码管理**：符合规范的密码设置（6-10位，含大小写字母和数字），支持密码修改功能
3. **年级选择**：支持小学、初中和高中三个不同阶段的数学题目
4. **智能题目生成**：根据选择的年级生成相应难度的数学选择题，同一张卷子不会有重复题目
5. **交互式答题**：逐题展示题目和选项，提供进度显示
6. **成绩反馈**：答题完成后显示得分和正确率
7. **答题记录**：系统会记录用户已做过的题目，避免重复出题
## 三、技术栈
- **编程语言**：Java
- **UI框架**：JavaFX
- **数据存储**：文件系统（JSON格式）
- **邮件服务**：JavaMail API
- **数学表达式解析**：exp4j 0.4.8
- **JSON处理**：Google Gson
## 四、安装与使用
### 环境要求
- JDK 17
- JavaFX 17（注意要与Java版本匹配）
- Maven（直接运行jar就不需要）
- 互联网连接（用于发送注册验证码）
- Windows系统
### 安装步骤
1. 确保已安装JDK 17并加入PATH，可通过在终端执行以下命令查看JDK版本：
```bash
java -version
```
2. 下载项目代码到本地
3. 在代码根目录打开Windows终端
### 构建（如果只是运行可执行文件，可以直接跳到运行的步骤）
```bash
mvn clean package
```
### 运行
**方法一：（相当于编译运行源码）**
```bash
mvn javafx:run
```
**方法二：(运行jar可执行文件)**
```bash
$repo = "C:\javafx-sdk-17.0.16\lib" //注意要改成自己的javafx的lib路径
$mp = "$repo\javafx.base.jar;" +
"$repo\javafx.controls.jar;" +
"$repo\javafx.fxml.jar;" +
"$repo\javafx.graphics.jar"
java --module-path $mp --add-modules javafx.controls,javafx.fxml,javafx.graphics -cp D:\math-tutor-1.0.jar edu.math.MainApp
//注意这个D:\math-tutor-1.0.jar
```
**注意：**
```text
1）两个$$直接复制一起粘到终端上就可以 不要一行一行复制！！！
2）第一行$repo = 后面要跟自己的javafx的lib的路径
3）最后一行中的D:\math-tutor-1.0.jar edu.math.MainApp要替换为自己的math-tutor-1.0.jar的路径+edu.math.MainApp
```
### 使用流程
1. **注册账号**：
- 点击"注册"按钮
- 输入用户名和邮箱
- 点击"发送验证码"，查看邮箱获取验证码
- 输入验证码和设置密码
- 点击"注册"完成账号创建
2. **登录系统**：
- 输入用户名/邮箱和密码
- 点击"登录"进入系统
3. **开始练习**：
- 选择相应的年级（小学、初中或高中）
- 输入需要生成的题目数量（10-30题）
- 点击"开始答题"进入答题界面
4. **答题过程**：
- 系统逐题展示题目和选项
- 选择答案后点击"提交"进入下一题
- 答题进度会实时显示
5. **查看成绩**：
- 完成所有题目后，系统显示得分和正确率
- 可以选择"退出"登录或"继续做题"
6. **修改密码**：
- 在年级选择界面点击"修改密码"按钮
- 输入原密码和新密码
- 确认新密码后点击"提交"完成修改
## 五、项目结构
```
src/
├── main/
│ ├── java/
│ │ └── edu/
│ │ └── math/
│ │ ├── MainApp.java # 应用程序入口
│ │ ├── controller/ # 控制器类
│ │ │ ├── ChangePasswordController.java # 修改密码控制器
│ │ │ ├── GradeSelectController.java # 年级选择控制器
│ │ │ ├── LoginController.java # 登录控制器
│ │ │ ├── QuizController.java # 答题控制器
│ │ │ ├── RegisterController.java # 注册控制器
│ │ │ └── ResultController.java # 结果显示控制器
│ │ ├── model/ # 数据模型类
│ │ │ ├── AbstractQuestionGenerator.java # 题目生成器抽象类
│ │ │ ├── ChoiceQuestion.java # 选择题模型
│ │ │ ├── JuniorQuestionGenerator.java # 初中题目生成器
│ │ │ ├── PrimaryQuestionGenerator.java # 小学题目生成器
│ │ │ ├── QuestionGenerator.java # 题目生成器工厂类
│ │ │ ├── SeniorQuestionGenerator.java # 高中题目生成器
│ │ │ ├── User.java # 用户模型
│ │ │ └── UserManager.java # 用户管理类
│ │ └── utils/ # 工具类
│ │ ├── CodeUtil.java # 验证码生成工具
│ │ ├── EmailUtil.java # 邮件发送工具
│ │ ├── FileUtil.java # 文件操作工具
│ │ └── ValidationUtil.java # 数据验证工具
│ └── resources/
│ └── view/ # FXML界面文件
│ ├── change_password.fxml # 修改密码界面
│ ├── grade_select.fxml # 年级选择界面
│ ├── login.fxml # 登录界面
│ ├── quiz.fxml # 答题界面
│ ├── register.fxml # 注册界面
│ └── result.fxml # 结果显示界面
```
## 六、核心类与功能说明
### 1. 应用程序入口
#### `MainApp.java`
- 应用程序的主入口点，继承自JavaFX的Application类
- 负责初始化并显示登录界面
- 设置应用程序窗口标题和大小
### 2. 数据模型层
#### `User.java`
- 用户实体类，包含用户基本信息
- **属性**：username（用户名）、email（邮箱）、password（密码）、grade（年级）
- **方法**：提供所有属性的getter和setter方法
#### `UserManager.java`
- 用户管理核心类，处理用户相关业务逻辑
- **主要方法**：
- `register(String username, String email, String password)`：用户注册
- `login(String identifier, String password)`：用户登录（支持用户名或邮箱）
- `usernameExists(String username)`：检查用户名是否存在
- `userExists(String email)`：检查邮箱是否存在
- `setGrade(String email, String grade)`：设置用户年级
- `changePassword(String email, String oldPwd, String newPwd)`：修改用户密码
#### `ChoiceQuestion.java`
- 选择题模型类
- **属性**：stem（题干）、options（选项数组）、correctIndex（正确答案索引）
- **方法**：提供所有属性的getter方法
#### 题目生成相关类
- **`AbstractQuestionGenerator.java`**：题目生成器抽象基类
- 定义题目生成的通用接口
- 包含随机数生成器和已存在题目集合的引用
- **`QuestionGenerator.java`**：题目生成器工厂类
- 根据选择的年级创建相应的题目生成器实例
- 提供生成选择题的方法
- **`PrimaryQuestionGenerator.java`**：小学题目生成器
- 生成适合小学生的数学题目
- 包含简单的加减乘除运算
- **`JuniorQuestionGenerator.java`**：初中题目生成器
- 生成适合初中生的数学题目
- 包含方程、几何等初中数学知识点
- **`SeniorQuestionGenerator.java`**：高中题目生成器
- 生成适合高中生的数学题目
- 包含函数、三角函数等高中数学知识点
### 3. 控制器层
#### `LoginController.java`
- 登录界面控制器
- **主要功能**：
- 处理用户登录逻辑
- 提供注册页面入口
- 验证用户输入并给出反馈
#### `RegisterController.java`
- 注册界面控制器
- **主要功能**：
- 处理用户注册逻辑
- 发送验证码到用户邮箱
- 实现验证码倒计时功能
- 验证用户输入的合法性
#### `GradeSelectController.java`
- 年级选择界面控制器
- **主要功能**：
- 提供小学、初中、高中三个选项
- 允许用户设置题目数量
- 提供修改密码功能入口
- 跳转到答题界面
#### `QuizController.java`
- 答题界面控制器
- **主要功能**：
- 初始化试卷和题目
- 逐题展示题目和选项
- 记录用户答案
- 计算得分并跳转到结果界面
- 处理长文本显示问题
#### `ChangePasswordController.java`
- 修改密码界面控制器
- **主要功能**：
- 验证原密码正确性
- 检查新密码是否符合规范
- 更新用户密码
#### `ResultController.java`
- 结果显示界面控制器
- **主要功能**：
- 显示用户得分和正确率
- 提供继续做题或退出的选项
### 4. 工具类
#### `FileUtil.java`
- 文件操作工具类
- **主要功能**：
- 保存和加载用户数据
- 管理用户名到邮箱的映射关系
- 管理用户答题记录
- 确保用户目录和试卷目录存在
#### `EmailUtil.java`
- 邮件发送工具类
- **主要功能**：
- 配置SMTP服务器信息
- 发送注册验证码邮件
#### `CodeUtil.java`
- 验证码生成工具类
- **主要功能**：
- 生成随机验证码
- 保存验证码与邮箱的对应关系
- 验证用户输入的验证码
#### `ValidationUtil.java`
- 数据验证工具类
- **主要功能**：
- 验证邮箱格式是否正确
- 验证密码是否符合安全规范（6-10位，含大小写字母和数字）
## 七、界面文件说明
- **`login.fxml`**：登录界面，包含用户名/邮箱输入框、密码输入框、登录和注册按钮
- **`register.fxml`**：注册界面，包含用户名、邮箱、验证码、密码和确认密码输入框，以及发送验证码和注册按钮
- **`grade_select.fxml`**：年级选择界面，包含小学、初中、高中单选按钮，题目数量输入框，开始答题和修改密码按钮
- **`quiz.fxml`**：答题界面，包含题目显示区域、选项区域、进度显示和提交按钮
- **`change_password.fxml`**：修改密码界面，包含原密码、新密码和确认新密码输入框，以及提交按钮
- **`result.fxml`**：结果显示界面，包含得分显示和继续/退出选项
## 八、数据存储说明
### 用户数据
- 用户数据以JSON格式存储在`./users/`目录下
- 文件名格式为`[邮箱转换格式].user`
- `username_to_email.json`文件存储用户名到邮箱的映射关系
### 答题记录
- 用户答题记录存储在`./papers/`目录下
- 按用户邮箱分类存储
- 记录用户已做过的题目，避免重复出题
## 九、安全注意事项
1. 密码安全：系统验证密码必须包含大小写字母和数字，长度在6-10位之间
2. 验证码安全：通过邮箱发送验证码，防止恶意注册
3. 文件安全：用户数据以文件形式存储，需确保文件系统访问权限设置正确
## 十、扩展与优化方向
1. 添加更多题型支持（如填空题、判断题等）
2. 实现题目难度分级
3. 添加错题本功能，记录用户错误的题目
4. 提供题目解析和学习建议
5. 优化UI界面，使其更加美观，提供更良好的用户体验
6. 添加学习进度统计和可视化功能
## 十一、常见问题与解决方案
1. **无法接收验证码邮件**
- 检查邮箱地址是否正确
- 检查垃圾邮件文件夹
- 确认网络连接正常
2. **密码设置失败**
- 确保密码符合要求：6-10位，包含大小写字母和数字
- 两次输入的密码必须一致
3. **题目生成失败**
- 确保选择了正确的年级
- 题目数量必须在10-30之间
4. **无法修改密码**
- 确认原密码输入正确
- 新密码必须符合安全要求
## 十二、作者
- 姓名1：王奕苏 学号：202326010308
# 数学学习软件 - 详细说明文档
## 一、项目简介
本项目是一款面向小学、初中和高中学生的数学学习软件，通过图形化界面提供个性化的数学题目生成与练习功能。系统支持用户注册登录、密码管理、年级选择、题目生成、答题练习和成绩展示等功能，所有数据均通过文件系统存储，无需额外的数据库支持。
## 二、功能特点
1. **用户注册与登录**：支持邮箱注册（包含验证码验证），支持用户名或邮箱登录
2. **密码管理**：符合规范的密码设置（6-10位，含大小写字母和数字），支持密码修改功能
3. **年级选择**：支持小学、初中和高中三个不同阶段的数学题目
4. **智能题目生成**：根据选择的年级生成相应难度的数学选择题，同一张卷子不会有重复题目
5. **交互式答题**：逐题展示题目和选项，提供进度显示
6. **成绩反馈**：答题完成后显示得分和正确率
7. **答题记录**：系统会记录用户已做过的题目，避免重复出题
## 三、技术栈
- **编程语言**：Java
- **UI框架**：JavaFX
- **数据存储**：文件系统（JSON格式）
- **邮件服务**：JavaMail API
- **数学表达式解析**：exp4j 0.4.8
- **JSON处理**：Google Gson
## 四、安装与使用
### 环境要求
- JDK 17
- JavaFX 17（注意要与Java版本匹配）
- Maven（直接运行jar就不需要）
- 互联网连接（用于发送注册验证码）
- Windows系统
### 安装步骤
1. 确保已安装JDK 17并加入PATH，可通过在终端执行以下命令查看JDK版本：
```bash
java -version
```
2. 下载项目代码到本地
3. 在代码根目录打开Windows终端
### 构建（如果只是运行可执行文件，可以直接跳到运行的步骤）
```bash
mvn clean package
```
### 运行
**方法一：（相当于编译运行源码）**
```bash
mvn javafx:run
```
**方法二：(运行jar可执行文件)**
```bash
//注意要改成自己的javafx的lib路径
$repo = "C:\javafx-sdk-17.0.16\lib"
$mp = "$repo\javafx.base.jar;" +
"$repo\javafx.controls.jar;" +
"$repo\javafx.fxml.jar;" +
"$repo\javafx.graphics.jar"
java --module-path $mp --add-modules javafx.controls,javafx.fxml,javafx.graphics -cp D:\math-tutor-1.0.jar edu.math.MainApp
//注意这个D:\math-tutor-1.0.jar
```
**注意：**
```text
1）两个$$直接复制一起粘到终端上就可以 不要一行一行复制！！！
2）第一行$repo = 后面要跟自己的javafx的lib的路径
3）最后一行中的D:\math-tutor-1.0.jar edu.math.MainApp要替换为自己的math-tutor-1.0.jar的路径+edu.math.MainApp
```
### 使用流程
1. **注册账号**：
- 点击"注册"按钮
- 输入用户名和邮箱
- 点击"发送验证码"，查看邮箱获取验证码
- 输入验证码和设置密码
- 点击"注册"完成账号创建
2. **登录系统**：
- 输入用户名/邮箱和密码
- 点击"登录"进入系统
3. **开始练习**：
- 选择相应的年级（小学、初中或高中）
- 输入需要生成的题目数量（10-30题）
- 点击"开始答题"进入答题界面
4. **答题过程**：
- 系统逐题展示题目和选项
- 选择答案后点击"提交"进入下一题
- 答题进度会实时显示
5. **查看成绩**：
- 完成所有题目后，系统显示得分和正确率
- 可以选择"退出"登录或"继续做题"
6. **修改密码**：
- 在年级选择界面点击"修改密码"按钮
- 输入原密码和新密码
- 确认新密码后点击"提交"完成修改
## 五、项目结构
```
src/
├── main/
│ ├── java/
│ │ └── edu/
│ │ └── math/
│ │ ├── MainApp.java # 应用程序入口
│ │ ├── controller/ # 控制器类
│ │ │ ├── ChangePasswordController.java # 修改密码控制器
│ │ │ ├── GradeSelectController.java # 年级选择控制器
│ │ │ ├── LoginController.java # 登录控制器
│ │ │ ├── QuizController.java # 答题控制器
│ │ │ ├── RegisterController.java # 注册控制器
│ │ │ └── ResultController.java # 结果显示控制器
│ │ ├── model/ # 数据模型类
│ │ │ ├── AbstractQuestionGenerator.java # 题目生成器抽象类
│ │ │ ├── ChoiceQuestion.java # 选择题模型
│ │ │ ├── JuniorQuestionGenerator.java # 初中题目生成器
│ │ │ ├── PrimaryQuestionGenerator.java # 小学题目生成器
│ │ │ ├── QuestionGenerator.java # 题目生成器工厂类
│ │ │ ├── SeniorQuestionGenerator.java # 高中题目生成器
│ │ │ ├── User.java # 用户模型
│ │ │ └── UserManager.java # 用户管理类
│ │ └── utils/ # 工具类
│ │ ├── CodeUtil.java # 验证码生成工具
│ │ ├── EmailUtil.java # 邮件发送工具
│ │ ├── FileUtil.java # 文件操作工具
│ │ └── ValidationUtil.java # 数据验证工具
│ └── resources/
│ └── view/ # FXML界面文件
│ ├── change_password.fxml # 修改密码界面
│ ├── grade_select.fxml # 年级选择界面
│ ├── login.fxml # 登录界面
│ ├── quiz.fxml # 答题界面
│ ├── register.fxml # 注册界面
│ └── result.fxml # 结果显示界面
```
## 六、核心类与功能说明
### 1. 应用程序入口
#### `MainApp.java`
- 应用程序的主入口点，继承自JavaFX的Application类
- 负责初始化并显示登录界面
- 设置应用程序窗口标题和大小
### 2. 数据模型层
#### `User.java`
- 用户实体类，包含用户基本信息
- **属性**：username（用户名）、email（邮箱）、password（密码）、grade（年级）
- **方法**：提供所有属性的getter和setter方法
#### `UserManager.java`
- 用户管理核心类，处理用户相关业务逻辑
- **主要方法**：
- `register(String username, String email, String password)`：用户注册
- `login(String identifier, String password)`：用户登录（支持用户名或邮箱）
- `usernameExists(String username)`：检查用户名是否存在
- `userExists(String email)`：检查邮箱是否存在
- `setGrade(String email, String grade)`：设置用户年级
- `changePassword(String email, String oldPwd, String newPwd)`：修改用户密码
#### `ChoiceQuestion.java`
- 选择题模型类
- **属性**：stem（题干）、options（选项数组）、correctIndex（正确答案索引）
- **方法**：提供所有属性的getter方法
#### 题目生成相关类
- **`AbstractQuestionGenerator.java`**：题目生成器抽象基类
- 定义题目生成的通用接口
- 包含随机数生成器和已存在题目集合的引用
- **`QuestionGenerator.java`**：题目生成器工厂类
- 根据选择的年级创建相应的题目生成器实例
- 提供生成选择题的方法
- **`PrimaryQuestionGenerator.java`**：小学题目生成器
- 生成适合小学生的数学题目
- 包含简单的加减乘除运算
- **`JuniorQuestionGenerator.java`**：初中题目生成器
- 生成适合初中生的数学题目
- 包含方程、几何等初中数学知识点
- **`SeniorQuestionGenerator.java`**：高中题目生成器
- 生成适合高中生的数学题目
- 包含函数、三角函数等高中数学知识点
### 3. 控制器层
#### `LoginController.java`
- 登录界面控制器
- **主要功能**：
- 处理用户登录逻辑
- 提供注册页面入口
- 验证用户输入并给出反馈
#### `RegisterController.java`
- 注册界面控制器
- **主要功能**：
- 处理用户注册逻辑
- 发送验证码到用户邮箱
- 实现验证码倒计时功能
- 验证用户输入的合法性
#### `GradeSelectController.java`
- 年级选择界面控制器
- **主要功能**：
- 提供小学、初中、高中三个选项
- 允许用户设置题目数量
- 提供修改密码功能入口
- 跳转到答题界面
#### `QuizController.java`
- 答题界面控制器
- **主要功能**：
- 初始化试卷和题目
- 逐题展示题目和选项
- 记录用户答案
- 计算得分并跳转到结果界面
- 处理长文本显示问题
#### `ChangePasswordController.java`
- 修改密码界面控制器
- **主要功能**：
- 验证原密码正确性
- 检查新密码是否符合规范
- 更新用户密码
#### `ResultController.java`
- 结果显示界面控制器
- **主要功能**：
- 显示用户得分和正确率
- 提供继续做题或退出的选项
### 4. 工具类
#### `FileUtil.java`
- 文件操作工具类
- **主要功能**：
- 保存和加载用户数据
- 管理用户名到邮箱的映射关系
- 管理用户答题记录
- 确保用户目录和试卷目录存在
#### `EmailUtil.java`
- 邮件发送工具类
- **主要功能**：
- 配置SMTP服务器信息
- 发送注册验证码邮件
#### `CodeUtil.java`
- 验证码生成工具类
- **主要功能**：
- 生成随机验证码
- 保存验证码与邮箱的对应关系
- 验证用户输入的验证码
#### `ValidationUtil.java`
- 数据验证工具类
- **主要功能**：
- 验证邮箱格式是否正确
- 验证密码是否符合安全规范（6-10位，含大小写字母和数字）
## 七、界面文件说明
- **`login.fxml`**：登录界面，包含用户名/邮箱输入框、密码输入框、登录和注册按钮
- **`register.fxml`**：注册界面，包含用户名、邮箱、验证码、密码和确认密码输入框，以及发送验证码和注册按钮
- **`grade_select.fxml`**：年级选择界面，包含小学、初中、高中单选按钮，题目数量输入框，开始答题和修改密码按钮
- **`quiz.fxml`**：答题界面，包含题目显示区域、选项区域、进度显示和提交按钮
- **`change_password.fxml`**：修改密码界面，包含原密码、新密码和确认新密码输入框，以及提交按钮
- **`result.fxml`**：结果显示界面，包含得分显示和继续/退出选项
## 八、数据存储说明
### 用户数据
- 用户数据以JSON格式存储在`./users/`目录下
- 文件名格式为`[邮箱转换格式].user`
- `username_to_email.json`文件存储用户名到邮箱的映射关系
### 答题记录
- 用户答题记录存储在`./papers/`目录下
- 按用户邮箱分类存储
- 记录用户已做过的题目，避免重复出题
## 九、安全注意事项
1. 密码安全：系统验证密码必须包含大小写字母和数字，长度在6-10位之间
2. 验证码安全：通过邮箱发送验证码，防止恶意注册
3. 文件安全：用户数据以文件形式存储，需确保文件系统访问权限设置正确
## 十、扩展与优化方向
1. 添加更多题型支持（如填空题、判断题等）
2. 实现题目难度分级
3. 添加错题本功能，记录用户错误的题目
4. 提供题目解析和学习建议
5. 优化UI界面，使其更加美观，提供更良好的用户体验
6. 添加学习进度统计和可视化功能
## 十一、常见问题与解决方案
1. **无法接收验证码邮件**
- 检查邮箱地址是否正确
- 检查垃圾邮件文件夹
- 确认网络连接正常
2. **密码设置失败**
- 确保密码符合要求：6-10位，包含大小写字母和数字
- 两次输入的密码必须一致
3. **题目生成失败**
- 确保选择了正确的年级
- 题目数量必须在10-30之间
4. **无法修改密码**
- 确认原密码输入正确
- 新密码必须符合安全要求
## 十二、作者
- 姓名1：王奕苏 学号：202326010308
- 姓名2：邓辰熹 学号：202326010315
Write Preview
Loading…
Cancel
Save