# 数学学习软件（当前说明）

本说明已根据最新代码与构建流程全面更新，并清理了过时脚本与旧文档。你可按本文档直接开发、运行与打包应用。

## 概述

- 技术栈：Java 17、JavaFX 21、Maven、Jackson（JSON 持久化）、Jakarta Mail（SMTP）、Commons Lang。
- 功能：注册/登录、验证码发送（SMTP 或本地文件回退）、题目生成与作答、评分、试卷导出与打开。
- 数据存储：基于 JSON 文件，无需数据库。

## 当前状态（0.1.4）

- 邮件配置优先读取 `%APPDATA%\数学学习软件\data\smtp.env`，统一安装版与源码运行行为。
- “打开试卷文件夹”稳定指向 `%APPDATA%\数学学习软件\data\papers`，使用系统默认文件管理器打开。
- 打包使用 Maven 插件化流程，无需仓库内的旧脚本。

## 目录与数据路径

- 应用数据根：`%APPDATA%\数学学习软件\data`
- 用户数据：`%APPDATA%\数学学习软件\data\users.json`
- 验证码文件（未配置 SMTP 时）：`%APPDATA%\数学学习软件\data\outbox.txt`
- 试卷目录：`%APPDATA%\数学学习软件\data\papers`

## 开发运行

1. 安装 JDK 17+ 与 Maven 3.8+。
2. 在项目根执行：
   - 编译：`mvn -DskipTests package`
   - 运行：`mvn javafx:run`

## 安装包打包（Windows MSI）

执行：

```powershell
mvn -DskipTests -P no-jlink clean package jpackage:jpackage
```

产物位于：`target\jpackage\数学学习软件-<版本>.msi`

## SMTP 配置（可选）

在 `%APPDATA%\数学学习软件\data\smtp.env` 创建配置文件：

```
SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_USER=你的QQ邮箱
SMTP_PASS=你的授权码
SMTP_FROM=你的QQ邮箱
SMTP_SSL=true
```

- 使用 587 端口时，将 `SMTP_SSL=false`（STARTTLS）。
- 安装包会附带 `dist/data/smtp.env` 示例（来自 `smtp.env.example`），实际使用以 AppData 路径为准。
- 可选便利脚本：`configure_smtp_qq.ps1` 会设置系统级环境变量（保留）。

## 常见问题排查

- 验证码未收到：检查 AppData 中 `smtp.env` 内容与端口/SSL 设置；允许应用联网。
- 未配置 SMTP：验证码写入 `outbox.txt`，在“注册”页点击“打开验证码文件”查看。
- 打开试卷文件夹异常：当前实现使用 `Desktop.open`，目标路径为 `%APPDATA%\数学学习软件\data\papers`；如仍异常，请反馈你系统的 `%APPDATA%` 实际值。

## 维护说明

- 构建：`maven-jar-plugin` 输出主 JAR；`maven-dependency-plugin` 复制运行时依赖到 `dist/lib`；`maven-antrun-plugin` 生成带 Class-Path 的清单与示例数据；`jpackage-maven-plugin` 生成 MSI。
- 清理：仓库中的旧日志、备份与不再使用的脚本/文档已删除，避免混淆与错误依赖。

## 许可证

课堂/课程作业用途，无外部依赖的许可文本。