# 数学学习软件系统文档

## 注意事项
为了方便助教检查，特在此说明注意事项

事先说明：我们所有的功能都是经过了测试的，确认已经实现；

1.双击jar包就可直接进入界面，如若不行，则进入终端使用java -jar指令运行；

2.使用.json文件存储注册的用户信息，第一次使用需要注册，同时会在存储jar包的文件夹下创建data文件夹，users.json
文件存储用户信息；

3.经过测试可以真实发送邮件，如果没有收到可以看看是否存在垃圾箱中；

4.我们的界面有滚动条，部分提示和功能需要滚动后才可以看到；

5.如果点击一下无效，可尝试多点击几下，或稍微等待一会，因为在部分电脑上测试存在卡顿；
主要是跳转、发送验证码界面需要缓冲几秒钟。

## 项目概述

数学学习软件是一个基于JavaFX开发的桌面应用程序，提供数学题目练习和考试功能。系统支持用户注册、登录、密码修改，以及小学、初中、高中三个难度级别的数学题目练习。

## 系统架构

### 模块结构

```
com.mathlearning/
├── controller/     # 控制器层
├── model/         # 数据模型
├── service/       # 业务服务层
└── view/          # 用户界面
```

## 核心功能模块

### 1. 用户认证模块 (Auth)

#### 功能特性
- 用户注册（邮箱验证码验证）
- 用户登录（支持邮箱和用户名登录）
- 密码修改
- 用户名修改
- 用户信息管理

#### 核心类
- `AuthController` - 认证控制器
- `UserService` - 用户服务
- `EmailService` - 邮件服务

#### 注册流程
1. 输入邮箱和用户名
2. 获取邮箱验证码
3. 设置密码（6-10位，包含大小写字母和数字）
4. 完成注册

### 2. 题目管理模块 (Question)

#### 功能特性
- 按难度级别生成题目（小学、初中、高中）
- 题目去重机制
- 自动生成选项
- 支持多种题型

#### 难度级别
- **小学**：加减乘除基础运算
- **初中**：平方、开方、混合运算
- **高中**：三角函数运算

#### 核心类
- `QuestionService` - 题目生成服务
- `Question` - 题目模型
- `DifficultyLevel` - 难度级别枚举

### 3. 考试模块 (Exam)

#### 功能特性
- 自定义题目数量（10-30题）
- 题目导航（上一题/下一题）
- 答案保存
- 自动评分

#### 核心类
- `ExamController` - 考试控制器
- `ExamSession` - 考试会话
- `ExamView` - 考试界面

### 4. 数据存储模块

#### 存储方式
- JSON文件存储用户数据
- 自动创建数据目录
- 数据持久化

#### 核心类
- `FileStorageService` - 文件存储服务

## 用户界面

### 主要界面

#### 1. 登录界面 (LoginView)
- 邮箱/密码登录
- 注册账号入口
- 登录状态提示

#### 2. 注册界面 (RegisterView)
- 邮箱验证
- 用户名实时检查
- 密码强度验证
- 验证码输入

#### 3. 级别选择界面 (LevelSelectView)
- 显示用户信息
- 三个难度级别选择
- 题目数量设置（滑动条+输入框）
- 修改密码功能

#### 4. 考试界面 (ExamView)
- 题目显示
- 选项选择
- 进度指示
- 导航控制

#### 5. 成绩界面 (ScoreView)
- 得分显示
- 成绩评价
- 继续学习选项

#### 6. 修改密码界面 (ChangePasswordView)
- 当前密码验证
- 新密码格式检查
- 操作结果反馈

## 技术特性

### 1. 邮件服务
- 支持QQ邮箱SMTP发送
- 验证码有效期10分钟
- 发送频率限制（1分钟内只能发送一次）
- 备用模拟发送模式

### 2. 密码策略
- 长度：6-10位
- 必须包含：大写字母、小写字母、数字
- 修改密码时需要验证原密码

### 3. 用户名规则
- 长度：2-20个字符
- 允许：中文、英文、数字、下划线、连字符
- 实时检查可用性

### 4. 题目生成
- 智能去重机制
- 难度适配算法
- 选项自动生成
- 支持多种数学运算

### 数据存储
用户数据自动保存在 `data/users.json` 文件中。

## 使用流程

1. **注册账号**
    - 输入邮箱和用户名
    - 获取邮箱验证码
    - 设置符合要求的密码

2. **登录系统**
    - 使用邮箱或用户名登录
    - 进入级别选择界面

3. **开始学习**
    - 选择难度级别（小学/初中/高中）
    - 设置题目数量（10-30题）
    - 开始答题

4. **查看成绩**
    - 完成考试后查看得分
    - 获得成绩评价
    - 可选择继续学习或退出

5. **账户管理**
    - 修改密码
    - 修改用户名
    - 退出登录

## 错误处理

- 输入验证失败时显示明确提示
- 网络异常时的降级处理
- 数据保存失败的重试机制
- 用户操作错误的友好提示

*该文档最后更新日期：2025年*