MyMathQuiz_UI/doc/README.md

小初高数学学习软件 (Math Learning Software for K-12)

这是一个专为小学、初中、高中学生设计的桌面数学学习与测验软件。本项目作为软件工程导论课程的结对编程项目，旨在提供一个用户友好、功能完善的图形化学习工具，帮助学生通过练习来巩固数学知识。

本软件实现了前后端完全分离的架构，前端负责界面展示与用户交互，后端负责业务逻辑、数据处理与持久化，最终通过 jpackage 工具打包成一个免安装的 Windows 可执行文件。

---

✨ 功能特性 (Features)

• 用户注册：通过邮箱验证码进行安全注册，确保用户身份的真实性。
• 双重登录方式：支持 邮箱 或 用户名 登录，为用户提供便利。
• 密码管理：支持用户在登录状态下修改密码，所有密码均经过加密存储，保障账户安全。
• 分级题库：内置 小学、初中、高中 三个不同难度的数学题库，题目类型符合对应学段的教学大纲。
• 动态生成试卷：用户可自定义需要生成的题目数量，系统会根据所选难度，动态生成一张不含重复题目的试卷。
• 交互式答题界面：清爽的图形化界面，以单项选择题的形式呈现，用户可以方便地进行选择和提交。
• 自动评分：所有题目回答完毕后，系统会立即自动计算并显示本次测验的分数。
• 数据持久化：用户信息与用户的历史题目记录均通过本地 JSON 和文本文件进行存储（遵循项目要求，不使用数据库），程序关闭后数据不会丢失。

---

🛠️ 技术栈 (Technology Stack)

• 前端 (Frontend): JavaFX, FXML
• 后端 (Backend): Java 17
• 构建工具 (Build Tool): Apache Maven
• 打包工具 (Packaging): JDK jpackage
• 依赖库 (Libraries):
  • Gson: 用于处理用户数据的 JSON 序列化与反序列化。
  • Jakarta Mail: 用于实现注册时的邮件验证码功能。

---

🚀 如何运行 (Getting Started)

面向开发者 (For Developers)

1. 环境准备:

   • JDK 17 或更高版本
   • Apache Maven 3.6+
   • IntelliJ IDEA

2. 克隆项目:

   git clone https://bdgit.educoder.net/hnu202326010416/MyMathQuiz_UI.git
   cd MyMathQuiz_UI
   

3. 配置邮箱服务:

• 重要: 请修改 src/main/java/com/student/mathquiz/service/UserServiceImpl.java 文件中的 SENDER_EMAIL 和 SENDER_AUTHORIZATION_CODE 为你自己的发件人邮箱和授权码。

4. 构建项目:

   # 生成包含所有依赖的 "胖JAR"（位于 target 目录下）
   mvn clean package
   

5. 运行 JAR 文件:

   # 构建成功后，在项目根目录执行以下命令运行 JAR
   java -jar target/mathquiz-1.0-SNAPSHOT.jar
   

6. 在IDE中运行:

   # 直接通过 Maven 插件运行主程序
   mvn javafx:run
   

---

面向普通用户 (For Users)

方式一：直接运行 EXE（推荐）

找到打包后生成的 数学学习软件 文件夹。 双击文件夹内的 数学学习软件.exe 即可直接运行。 程序所需的数据文件（如 users.json）会自动在您的用户主目录下的 .mathquiz 文件夹中创建。

方式二：运行 JAR 文件

如果您已经安装了 JDK 17 或更高版本，可以直接运行 JAR 文件：

1. 确保您的电脑已安装 JDK 17。
2. 打开命令行工具（Windows 上是 CMD 或 PowerShell）。
3. 进入 JAR 文件所在目录。
4. 执行以下命令：

   java -jar mathquiz-1.0-SNAPSHOT.jar
   

5. 如果运行时提示 JavaFX 相关错误，请使用完整命令：

   java --module-path "path\to\javafx-sdk-17\lib" --add-modules javafx.base,javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.swing,javafx.web -jar mathquiz-1.0-SNAPSHOT.jar
   

   其中 path\to\javafx-sdk-17\lib 替换为您本地 JavaFX SDK 的实际路径。

---

📂 项目结构 (Project Structure)

本项目采用前后端分离的设计思想，将视图、业务逻辑和数据持久化清晰地分层。

src
└── main
    ├── java
    │   └── com/student/mathquiz
    │       ├── MainApp.java // 程序主入口，负责视图切换和前后端桥接
    │       ├── Launcher.java // 解决 JavaFX 模块化启动问题的启动器
    │       ├── constant/ // 存放常量和枚举 (后端)
    │       ├── model/ // 数据模型 (User, Question) (后端)
    │       ├── persistence/ // 数据持久化层 (文件读写) (后端)
    │       ├── question/ // 题目生成器 (后端)
    │       ├── service/ // 业务逻辑服务层 (IUserService, IQuizService) (后端)
    │       └── view/ // 视图控制器 (xxxController.java) (前端)
    └── resources
        └── com/student/mathquiz
            └── view/ // FXML 界面定义文件 (前端)

---

👨‍💻 开发成员 (Authors)

• 组长: 李瑜清 (学号: 202326010416)
• 组员: 马芳琼 (学号: 202326010423)

---

感谢使用！希望这个软件能帮助你更好地学习数学！