self_project/doc/README.md

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

目录

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. 用户登录验证

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. 题目去重机制

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. 表达式生成算法

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. 括号插入算法（高中）

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. 登录测试

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

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

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

2. 题目生成测试

# 测试小学题目
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. 文件操作测试

# 测试文件保存
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格式导出

接口设计

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

---