添加 'doc/README.MD'

doc/README.MD

@@ -0,0 +1,227 @@
+# 数学题目生成器 (图形化界面版) 项目说明文档
+
+
+
+
+
+## 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. **请勿删除**：上述两个文件夹是程序正常运行和数据持久化的关键。**请不要手动删除或修改这些文件夹及其中的内容**，否则将导致所有用户账号信息和历史试卷记录丢失，且无法恢复。