# 中小学数学卷子自动生成程序 - 详细说明文档

## 目录
1. [项目概述](#项目概述)
2. [系统架构](#系统架构)
3. [功能详解](#功能详解)
4. [使用指南](#使用指南)
5. [技术实现](#技术实现)
6. [测试用例](#测试用例)
7. [部署说明](#部署说明)

## 项目概述

本程序是一个面向中小学数学教师的智能试卷生成系统，能够根据不同的学段要求自动生成符合教学大纲的数学题目。

### 设计目标
- 为小学、初中、高中教师提供个性化的试卷生成服务
- 确保题目难度与学段匹配
- 避免题目重复，保证每次生成的试卷都是唯一的
- 提供友好的命令行交互界面

## 系统架构

### 类图结构
```
ExamSystem
├── User
├── QuestionGenerator
│   ├── PrimarySchoolGenerator
│   ├── MiddleSchoolGenerator
│   └── HighSchoolGenerator
└── 文件管理模块
```

### 主要类说明

#### 1. User类
- 属性：username, password, user_type
- 功能：存储用户信息和权限

#### 2. QuestionGenerator基类
- 抽象方法：generate_question()
- 通用方法：生成操作数、运算符

#### 3. 各学段生成器
- PrimarySchoolGenerator：小学题目生成
- MiddleSchoolGenerator：初中题目生成  
- HighSchoolGenerator：高中题目生成

#### 4. ExamSystem主类
- 用户管理：登录验证、会话管理
- 题目生成：协调各生成器工作
- 文件操作：试卷保存、题目去重

## 功能详解

### 1. 用户登录验证
```python
def login(self) -> bool:
    # 实现用户名密码验证
    # 支持9个预设账号
    # 提供友好的错误提示
```

### 2. 题目生成算法

#### 小学题目
- 操作数：2-3个随机数（1-100）
- 运算符：仅使用 + 和 -
- 示例："23 + 45 - 12"

#### 初中题目  
- 操作数：3-4个随机数（1-100）
- 运算符：+、-、*、/
- 示例："15 * 3 + 28 / 4"

#### 高中题目
- 操作数：4-5个随机数（1-100）
- 运算符：+、-、*、/
- 括号：30%概率包含括号运算
- 示例："(15 + 3) * 2 - 8 / 4"

### 3. 题目去重机制
```python
def load_existing_questions(self, username: str) -> Set[str]:
    # 加载用户所有历史题目
    # 使用集合实现快速查找

def generate_unique_question(self, generator, existing_questions):
    # 生成题目并检查是否重复
    # 最大尝试次数100次
```

### 4. 文件存储系统
- 目录结构：papers/用户名/
- 文件名：年-月-日-时-分-秒.txt
- 格式：题号 + 题目 + 空行

## 使用指南

### 快速开始
1. 确保安装Python 3.6+
2. 下载项目代码
3. 运行命令：`python src/main.py`

### 交互命令说明

#### 登录阶段
```
请输入用户名和密码（用空格隔开）：primary_teacher1 primary123
当前选择为 小学 出题
```

#### 生成试卷
```
准备生成 小学 数学题目，请输入生成题目数量（输入-1将退出当前用户，重新登录）：
>>> 15
试卷已生成：papers/primary_teacher1/2025-01-15-14-30-25.txt
```

#### 切换学段
```
>>> 切换为 初中
已切换为 初中 出题
准备生成 初中 数学题目，请输入生成题目数量：
>>> 20
```

#### 退出操作
```
>>> -1
退出当前用户
```

## 技术实现

### 核心算法

#### 1. 表达式生成算法
```python
def generate_question(self) -> str:
    num_operands = random.randint(2, 3)
    operands = self.generate_operands(num_operands)
    operators = [random.choice(['+', '-']) for _ in range(num_operands - 1)]
    
    # 构建表达式
    expression = str(operands[0])
    for i in range(num_operands - 1):
        expression += f" {operators[i]} {operands[i + 1]}"
    
    return expression
```

#### 2. 括号插入算法（高中）
```python
def _generate_with_brackets(self, operands, operators):
    if len(operands) <= 3 or random.random() < 0.3:
        # 简单表达式或不加括号
        return simple_expression
    
    # 随机选择插入括号的位置
    bracket_pos = random.randint(0, len(operands) - 3)
    # 构建带括号的表达式
```

### 错误处理
- 输入验证：检查用户名密码格式
- 数量验证：题目数量必须在10-30之间
- 类型验证：切换学段时检查有效性
- 文件操作：异常处理和重试机制

### 性能优化
- 使用集合进行快速去重查找
- 限制最大尝试次数防止无限循环
- 惰性加载历史题目

## 测试用例

### 功能测试

#### 1. 登录测试
```python
# 测试正确登录
assert login("primary_teacher1", "primary123") == True

# 测试错误密码  
assert login("primary_teacher1", "wrong") == False

# 测试不存在的用户
assert login("nonexistent", "123") == False
```

#### 2. 题目生成测试
```python
# 测试小学题目
question = PrimarySchoolGenerator().generate_question()
assert question.count('+') + question.count('-') >= 1
assert '*' not in question and '/' not in question

# 测试题目去重
existing = {"1 + 2"}
new_question = generate_unique_question(generator, existing)
assert new_question != "1 + 2"
```

#### 3. 文件操作测试
```python
# 测试文件保存
filename = save_exam_paper(["1 + 1", "2 * 2"])
assert os.path.exists(filename)

# 测试文件格式
content = read_file(filename)
assert "1. 1 + 1" in content
assert "\n\n2. 2 * 2" in content
```

## 部署说明

### 环境要求
- Python 3.6或更高版本
- 磁盘空间：至少10MB用于存储试卷文件
- 内存：最少128MB RAM

### 安装步骤
1. 下载项目代码
2. 无需安装依赖（使用标准库）
3. 直接运行：`python src/main.py`

### 文件结构部署
```
项目根目录/
├── src/                 # 源代码
│   └── main.py         # 主程序
├── doc/                # 文档
│   └── README.md       # 详细说明
├── papers/             # 试卷存储（自动创建）
└── README.md           # 项目简介
```

### 维护说明
- 定期清理papers目录下的旧试卷文件
- 如需修改预设账号，编辑main.py中的users列表
- 支持自定义题目生成规则

## 扩展性

### 可扩展功能
1. **题目难度调节**：增加难度级别参数
2. **题目类型扩展**：支持几何、代数等不同类型
3. **批量生成**：支持一次生成多份试卷
4. **Web界面**：开发图形化操作界面
5. **题目导出**：支持PDF、Word格式导出

### 接口设计
```python
# 可扩展的题目生成器接口
class QuestionGenerator:
    def set_difficulty(self, level: int):
        """设置题目难度"""
        
    def generate_with_topics(self, topics: List[str]):
        """按主题生成题目"""
```

---