v1.0

doc/README.md

@@ -0,0 +1,111 @@
+# 中小学数学题生成系统 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`）。