math-problem-generator/doc

中小学数学题生成系统 README

一、项目介绍

本系统是一款面向中小学场景的数学题自动生成工具，支持按学段（小学/初中/高中）生成对应难度题目，集成登录验证、学段切换、重复题目检测、本地保存等功能，满足教学练习中的题目生成需求。

二、运行环境要求

依赖项	版本要求	说明
JDK	JDK 1.8 及以上	需配置 JAVA_HOME 环境变量
运行载体	可执行 JAR / IntelliJ IDEA	推荐直接运行 JAR 包
操作系统	Windows 10/11、macOS	跨平台兼容

三、核心功能说明

1. 登录验证

• 预设测试账户（按学段分类）：
  • 小学：张三1/123、张三2/123、张三3/123
  • 初中：李四1/123、李四2/123、李四3/123
  • 高中：王五1/123、王五2/123、王五3/123
• 输入校验：支持用户名密码格式检测，错误时提示“输入格式错误”或“用户名/密码错误”。

2. 题目生成（按学段区分）

• 小学题：无负数、可整除的加减乘除运算（支持括号，如 (4 + 6) × 3）
• 初中题：小学题基础上新增平方（^2）、根号（√），如 5^2 - √16
• 高中题：小学题基础上新增三角函数（sin/cos/tan），如 tan(45) + 8
• 数量限制：每次生成 10-30 道题，超出范围会提示调整。

3. 学段切换

• 操作逻辑：登录后选择“1-切换学段”或“0-保持当前学段”，支持小学/初中/高中三选一。
• 错误处理：输入非“0/1”或非学段名称（如“大学”）时，提示重新输入，直至合法。

4. 重复题目检测（查重）

• 检测范围：自动扫描当前用户文件夹下所有历史 .txt 题目文件。
• 匹配规则：排除题号干扰，仅精确对比题目内容（如 2 + 3 不会与 12 + 3 误判重复）。
• 处理方式：生成重复题目时自动重新生成，确保输出题目无重复。

5. 题目保存

• 保存路径：项目根目录自动创建“用户名”文件夹（如 张三1），题目保存在该文件夹内。
• 文件名格式：yyyy-MM-dd-HH-mm-ss.txt（时间戳命名，避免文件覆盖）。
• 内容格式（带题号+空行分隔）：

  1. 3 + 7 × 2
  
  2. sin(30) + √9
  

四、使用步骤

方式1：直接运行 JAR 包（推荐）

1. 获取 JAR 包：从项目 out/artifacts/ 目录复制 MyProject.jar 到目标文件夹（如 D:\MathTool）。
2. 打开命令行：
   • Windows：Win + R 输入 cmd，进入 JAR 所在目录（示例：cd D:\MathTool）。
   • 解决中文乱码：执行 chcp 65001（切换 cmd 编码为 UTF-8）。
3. 启动系统：执行 java -jar MyProject.jar。
4. 操作流程： ① 输入预设账户（如 张三1 123）登录； ② 选择“0-保持学段”或“1-切换学段”； ③ 输入题目数量（10-30），等待生成保存； ④ 生成后可选择“-2 继续出题”“-1 返回主页”“-3 退出系统”。

方式2：IntelliJ IDEA 中运行

1. 导入项目：打开 IDEA → 选择“Open” → 导入项目文件夹（MyProject）。
2. 配置 JDK：File → Project Structure → Project SDK 选择 JDK 1.8 及以上。
3. 启动主类：找到 src/Main.java → 右键“Run Main.main()”。
4. 后续操作：同“方式1”步骤4。

五、项目目录结构

MyProject/
├─ src/                  # 源码目录
│  ├─ account/           # 登录相关类
│  │  ├─ Account.java    # 账户实体（用户名/密码/学段）
│  │  ├─ AccountService.java  # 登录接口
│  │  └─ SimpleAccountService.java  # 登录实现（预设账户）
│  ├─ persistence/       # 持久化相关类
│  │  ├─ FileSaver.java  # 题目保存类
│  │  └─ QuestionChecker.java  # 查重类
│  ├─ question/          # 题目生成相关类
│  │  ├─ Question.java   # 题目实体（内容/答案）
│  │  ├─ QuestionGenerator.java  # 题目生成接口
│  │  ├─ PrimaryQuestionGenerator.java  # 小学题生成
│  │  ├─ MiddleQuestionGenerator.java  # 初中题生成
│  │  └─ HighQuestionGenerator.java  # 高中题生成
│  └─ Main.java          # 程序入口（主类）
├─ out/                  # 编译输出目录
│  └─ artifacts/         # JAR 包输出目录（MyProject.jar）
└─ README.md             # 项目说明文档

六、常见问题（FAQ）

Q1：运行 JAR 提示“找不到或无法加载主类”？

A1：重新通过 IDEA 导出 JAR（File → Project Structure → Artifacts → Build），确保导出路径正确。

Q2：输入中文用户名/密码后显示乱码？

A2：在 cmd 中先执行 chcp 65001 切换编码，再运行 JAR。

Q3：账户正确却提示“登录失败”？

A3：确认输入时用 半角空格（英文空格）分隔用户名和密码，避免全角空格（中文空格）。

Q4：生成题目后找不到文件？

A4：文件保存在“项目根目录/用户名/时间戳.txt”，示例：MyProject/张三1/2024-05-20-15-40-00.txt。

七、代码规范说明

1. 设计原则：采用“接口先行”模式（如 AccountService、QuestionGenerator），降低模块耦合。
2. 方法行数：所有方法行数 ≤ 40 行，通过拆分逻辑（如 generateAndSaveQuestions）提升可读性。
3. 容错处理：包含输入校验、异常捕获（如 NumberFormatException）、空值判断，避免程序崩溃。
4. 命名规范：遵循 Java 标准（类名 PascalCase、方法名 camelCase），语义化命名（如 switchType、questionLoop）。