wys_dcx_double_proj/doc

数学学习软件 - 详细说明文档

一、项目简介

本项目是一款面向小学、初中和高中学生的数学学习软件，通过图形化界面提供个性化的数学题目生成与练习功能。系统支持用户注册登录、密码管理、年级选择、题目生成、答题练习和成绩展示等功能，所有数据均通过文件系统存储，无需额外的数据库支持。

二、功能特点

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版本：

java -version

2. 下载项目代码到本地
3. 在代码根目录打开Windows终端

构建（如果只是运行可执行文件，可以直接跳到运行的步骤）

mvn clean package

运行

方法一：（相当于编译运行源码）

mvn javafx:run

方法二：(运行jar可执行文件)

//注意要改成自己的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

注意：

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