doc/README.md

@@ -0,0 +1,161 @@
+# ExamGenerator 项目
+
+本项目是一个 **数学试题自动生成系统**，支持 **小学、初中、高中** 三个年级的数学题目。
+系统采用 **抽象类 + 子类继承** 的设计模式，分别实现不同年级的出题逻辑，并支持用户登录、题目查重和自动保存功能。
+
+---
+
+## 📂 项目结构
+
+```
+ExamGenerator/
+├── main.py                    # 主入口程序
+├── exam_generator.py          # 考试生成器核心逻辑（含查重）
+├── account_manager.py         # 用户账户管理模块
+├── history_manager.py         # 历史管理模块（负责保存/读取历史题目）
+├── generators/                # 出题生成器目录
+│   ├── base_generator.py      # 抽象类：出题生成器基类
+│   ├── primary_generator.py   # 小学出题生成器
+│   ├── junior_generator.py    # 初中出题生成器
+│   └── senior_generator.py    # 高中出题生成器
+└── exams/                     # 保存生成的试卷目录
+```
+
+---
+
+## 功能介绍
+
+### 用户登录
+
+* 支持小学、初中、高中账号登录
+* 登录后自动进入对应出题模式
+
+### 出题生成
+
+* 小学：四则运算
+* 初中：四则运算 + 平方/开方
+* 高中：四则运算 + 三角函数
+
+### 历史查重
+
+* `HistoryManager` 只负责保存和读取历史题目
+* **查重逻辑已集成在 `ExamGenerator._generate_and_save_questions`**，生成题目时会自动避免重复
+
+### 题目保存
+
+* 生成的题目自动保存为 `.txt` 文件
+* 文件名格式：`YYYY-MM-DD-HH-MM-SS.txt`
+
+---
+
+## 使用方法
+
+### 运行项目（开发环境）
+
+```bash
+cd ExamGenerator
+python main.py
+```
+
+### 登录系统
+
+* 输入用户名和密码（例如：`张三1 123`）
+* 系统会识别年级，并提示你输入要生成的题目数量
+
+### 生成题目
+
+* 输入 `10-30` 之间的数字，生成对应数量的数学题
+* 输入 `-1` 可退出当前用户
+* 输入 `切换为 小学/初中/高中` 可切换出题难度
+
+---
+
+##  技术亮点
+
+* **抽象类设计**：使用 `BaseQuestionGenerator` 定义统一接口，小学/初中/高中继承实现
+* **模块化结构**：按功能拆分文件，便于维护和扩展
+* **查重机制优化**：查重逻辑整合进 `ExamGenerator`，`HistoryManager` 仅负责保存/读取
+* **可扩展性强**：后续可新增 “大学” 出题生成器，只需继承抽象类即可
+
+---
+
+## ⚠️ 注意事项
+
+* 默认账号信息存放在 `exam_generator.py` 中
+* 生成的题目文件会自动存放在 `exams/用户名/` 目录下
+* Python 版本需 **>= 3.8**
+
+---
+
+##  发布与运行（Release 版本）
+
+### Windows 平台
+
+1. 打包：
+
+   ```bash
+   pyinstaller --onefile main.py
+   ```
+
+   生成的 `main.exe` 位于 `dist/` 目录。
+
+2. 运行方式：
+
+   ```bash
+   main.exe
+   ```
+
+### Linux 平台
+
+1. 打包：
+
+   ```bash
+   pyinstaller --onefile main.py
+   ```
+
+   生成的可执行文件在 `dist/main`。
+
+2. 运行方式：
+
+   ```bash
+   ./main
+   ```
+
+   * 确保执行权限：`chmod +x main`
+   * 注意 Linux 路径分隔符为 `/`
+
+---
+
+##  参数设置
+
+发布版本运行时，需要在交互过程中输入以下参数：
+
+* **用户名**
+
+  * 例如：`张三1`
+  * 用于识别所属年级（小学/初中/高中）
+
+* **密码**
+
+  * 默认均为 `123`（可在 `exam_generator.py` 中修改）
+
+* **题目数量**
+
+  * 输入范围：`10 - 30`
+  * 系统会生成对应数量的题目
+  * 输入 `-1` 退出当前用户
+
+* **切换难度**
+
+  * 输入 `切换为 小学` / `切换为 初中` / `切换为 高中`
+  * 可在运行中调整题目难度
+
+---
+
+##  开发环境 vs 发布环境
+
+* **开发环境**：本地运行，需 Python >= 3.8
+* **发布环境**：打包成可执行文件（Windows 为 `.exe`，Linux 为二进制文件），用户无需安装 Python
+* **跨平台差异**：注意路径分隔符和执行权限的不同
+
+---