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

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

概述

• 技术栈：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）

执行：

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。
• 清理：仓库中的旧日志、备份与不再使用的脚本/文档已删除，避免混淆与错误依赖。

许可证

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