History

ymr 81b1185b67 添加 src 和 lib 核心代码		3 months ago
..
README.md	添加 src 和 lib 核心代码	3 months ago

README.md

Unescape Escape

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

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. 运行说明

启动程序 运行 Main.java 类，启动图形化登录窗口。
用户注册/登录
- 新用户点击“注册”，按照“输入邮箱/用户名 -> 发送验证邮件 -> 查收邮件验证码 -> 设置密码”的流程完成注册。
- 老用户可使用邮箱或用户名直接登录。
开始考试 在主菜单选择题目难度和数量，点击“开始答题”进入考试界面。
答题过程 通过“上一题”、“下一题”进行导航，随时可通过“交卷并评分”按钮结束考试。
查看分数 交卷后，分数界面会显示本次得分和答题详情。用户可选择“再来一组”或“退出登录”。

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 系统下运行步骤

配置 Java 22 编译环境

确保系统已安装 Java 22 JDK 版本
设置控制台编码

打开 cmd 命令行工具，使用以下指令执行 .jar 文件：
```
java -jar .\MathExamApp.jar
```

Linux 系统下运行步骤

配置 Java 22 JDK 版本

确保系统已安装 Java 22 JDK
运行程序

使用以下指令执行程序：

java -jar MathExamApp.jar

8. 注意事项

数据文件夹：程序第一次成功注册用户或生成试卷后，会在程序运行的根目录下自动创建以下文件夹：
- data/：此文件夹包含 users.txt 文件，用于存储所有用户的账号和密码信息。
- exams/：此文件夹下会以每个用户的邮箱/用户名创建子文件夹，用于存放该用户所有历史试卷的 .txt 文件。
请勿删除：上述两个文件夹是程序正常运行和数据持久化的关键。请不要手动删除或修改这些文件夹及其中的内容，否则将导致所有用户账号信息和历史试卷记录丢失，且无法恢复。

README.md Unescape Escape