doc/README.md

@@ -1,5 +1,196 @@
 ## 小初高数学学习软件 - 代码说明文档
 
+## 项目概述
+
+本项目是一个面向小学、初中和高中学生的数学学习软件，提供图形化界面的数学题目练习和测试功能。软件采用JavaFX开发，实现了用户注册、登录、题目生成、在线答题和成绩统计等完整功能。
+
+## 项目结构
+
+```
+src/
+├── Main.java                 # 主程序入口，界面控制器
+├── QuestionGenerator.java    # 题目生成器
+├── ExamManager.java          # 试卷管理器
+├── User.java                 # 用户实体类
+└── MailSender.java           # 邮件发送器
+```
+
+## 核心功能模块
+
+### 1. 用户管理模块
+
+#### 功能特性
+
+- **双方式登录**：支持邮箱或用户名登录
+- **用户注册**：邮箱验证、用户名设置（4-10位）
+- **密码管理**：6-10位，必须包含大小写字母和数字
+- **密码修改**：登录状态下可修改密码
+
+#### 核心代码
+
+```java
+// 用户验证方法
+private boolean isValidUsername(String username)    // 用户名格式验证
+private boolean isValidEmail(String email)          // 邮箱格式验证  
+private boolean isValidPassword(String password)    // 密码强度验证
+```
+
+### 2. 题目生成模块
+
+#### 题目难度分级
+
+**小学题目**
+
+- 运算符：+、-、*、/
+- 支持括号运算
+- 操作数：1-100
+- 操作数个数：2-5个
+
+**初中题目**  
+
+- 包含小学所有运算符
+- 新增：平方(^2)、开根号(√)
+- 确保每道题至少包含一个特殊运算符
+
+**高中题目**
+
+- 包含初中所有运算符
+- 新增：sin、cos、tan三角函数
+- 确保每道题至少包含一个三角函数
+
+#### 核心算法
+
+```java
+public String generateQuestion(String type)         // 根据类型生成题目
+public List<String> generateOptions(String answer)  // 生成选择题选项
+```
+
+### 3. 考试管理模块
+
+#### 功能特性
+
+- **题目查重**：同一试卷内题目不重复
+- **进度跟踪**：实时显示答题进度
+- **自动评分**：答完后自动计算分数
+- **成绩展示**：显示得分、正确率、详细统计
+
+#### 核心类
+
+```java
+public class ExamManager {
+    public List<String> generateExam(int numQuestions)  // 生成指定数量题目
+}
+```
+
+### 4. 界面导航流程
+
+```
+登录界面 → 注册界面 → 难度选择 → 题目数量输入 → 答题界面 → 成绩界面
+     ↑                                                       ↓
+     ←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←
+```
+
+## 技术实现细节
+
+### 1. 数据存储
+
+- 使用内存Map存储用户数据
+- 题目历史记录在Session中维护
+- 符合"不可以使用数据库存储数据"的要求
+
+### 2. 邮件服务
+
+- 使用QQ邮箱SMTP服务
+- 异步发送验证码
+- 支持注册验证功能
+
+### 3. 界面设计
+
+- 采用JavaFX图形界面
+- 响应式布局设计
+- 友好的用户交互提示
+
+## 代码规范与架构
+
+### 1. 类职责分离
+
+- `Main.java`：界面控制和业务流程
+- `QuestionGenerator.java`：题目生成算法
+- `ExamManager.java`：试卷管理逻辑
+- `User.java`：用户数据模型
+- `MailSender.java`：邮件服务封装
+
+### 2. 方法设计原则
+
+- 单一职责原则
+- 方法行数控制在40行以内
+- 清晰的参数和返回值定义
+
+## 配置要求
+
+### 运行环境
+
+- Java 8及以上
+- JavaFX SDK
+- 网络连接（用于邮件发送）
+
+### 邮箱配置
+
+在`Main.java`中修改发件邮箱配置：
+
+```java
+private MailSender mailSender = new MailSender("你的邮箱", "授权码");
+```
+
+## 功能验证清单
+
+### ✅ 已实现功能
+
+- [x] 图形化界面操作
+- [x] 用户注册与邮箱验证
+- [x] 密码强度验证（6-10位，大小写字母+数字）
+- [x] 双方式登录（邮箱/用户名）
+- [x] 密码修改功能
+- [x] 三难度题目生成（小学、初中、高中）
+- [x] 题目数量限制（10-30题）
+- [x] 选择题形式答题
+- [x] 自动评分与成绩展示
+- [x] 继续做题/退出选择
+
+### ✅ 符合项目要求
+
+- [x] 不使用数据库存储
+- [x] 所有功能通过图形界面操作
+- [x] 完整的用户流程
+- [x] 题目符合各学段难度要求
+
+## 使用说明
+
+1. **首次使用**：点击"前往注册"，设置用户名、邮箱，接收验证码完成注册
+2. **登录系统**：使用邮箱或用户名+密码登录
+3. **选择难度**：根据学习阶段选择小学、初中或高中
+4. **设置题量**：输入10-30之间的题目数量
+5. **开始答题**：逐题作答，系统自动记录进度
+6. **查看成绩**：答题完成后查看详细成绩统计
+7. **继续学习**：可选择继续做题或退出系统
+
+## 扩展建议
+
+1. **数据持久化**：添加文件存储避免重启数据丢失
+2. **题目查重优化**：跨会话题目历史记录
+3. **学习进度跟踪**：记录用户历史成绩和进步情况
+4. **错题本功能**：自动收集错题供复习使用
+
+## 开发者信息
+
+- **技术栈**：Java + JavaFX
+- **架构模式**：MVC模式
+- **代码规范**：遵循Java编码规范
+- **版本控制**：Git分支管理
+
+---
+
+*最后更新：2025年X月X日*# 小初高数学学习软件 - 代码说明文档
 
 ## 项目概述