获取原卷数据

获取指定学生的原卷完整数据，包括答题卡图片、答题详情、批改记录等，并可选择保存 HTML 文件。

功能更新

此接口已升级，不再仅仅是下载 HTML 文件，现在会解析原卷数据并返回结构化的 OriginalPaper 对象，包含答题详情、批改记录、答题卡图片等完整信息。

方法定义

def get_original_paper(
    user_id: str, 
    topic_set_id: str, 
    save_to_path: Optional[str] = None
) -> OriginalPaper

参数

参数	类型	默认值	描述
user_id	str	-	目标学生 ID
topic_set_id	str	-	学科 ID (Topic Set ID)
save_to_path	Optional[str]	None	保存 HTML 的路径（包含文件名），为 None 则不保存文件

返回值

返回 OriginalPaper 对象，包含以下信息：

OriginalPaper 对象属性

属性	类型	描述
user_id	str	学生 ID
topic_set_id	str	科目 ID
total_score	float	总分
answer_sheet_images	List[str]	答题卡图片 URL 列表
answer_details	List[AnswerRecordDetail]	答题详情列表

AnswerRecordDetail 对象属性

属性	类型	描述
topic_number	int	题号
disp_title	str	显示标题
answer	str	学生答案
score	float	得分
standard_score	float	满分
is_correct	bool	是否正确
answer_type	str	答题类型
sub_topics	List[SubTopicDetail]	小题详情（主观题）
is_excellent	bool	是否优秀答案
is_typical_error	bool	是否典型错误

SubTopicDetail 对象属性（主观题小题）

属性	类型	描述
score	float	小题得分
sub_topic_index	int	小题序号
teacher_marking_records	List[TeacherMarkingRecord]	教师批改记录

TeacherMarkingRecord 对象属性

属性	类型	描述
score	float	批改分数
marking_time	int	批改时间戳（毫秒）
teacher_name	str	批改教师姓名(目前总为空)
teacher_id	str	批改教师 ID
is_excellent	bool	是否标记为优秀
is_typical_error	bool	是否标记为典型错误
marking_content	str	批改内容/评语

示例代码

1. 获取原卷数据不保存文件

# 获取学生原卷数据
user_id = "student_123456"
topic_set_id = "subject_001"

original_paper = teacher.get_original_paper(user_id, topic_set_id)

# 查看基本信息
print(f"学生ID: {original_paper.user_id}")
print(f"科目ID: {original_paper.topic_set_id}")
print(f"总分: {original_paper.total_score}")
print()

# 查看答题卡图片
print(f"答题卡共 {len(original_paper.answer_sheet_images)} 页:")
for i, img_url in enumerate(original_paper.answer_sheet_images, 1):
    print(f"  第 {i} 页: {img_url}")
print()

# 查看答题详情
print("答题详情:")
for detail in original_paper.answer_details:
    print(f"题号 {detail.topic_number}: {detail.disp_title}")
    print(f"  得分: {detail.score}/{detail.standard_score}")
    print(f"  答案: {detail.answer}")
    print(f"  是否正确: {detail.is_correct}")
    
    # 如果有小题（主观题）
    if detail.sub_topics:
        for sub in detail.sub_topics:
            print(f"    小题 {sub.sub_topic_index}: {sub.score}分")
            # 查看批改记录
            for record in sub.teacher_marking_records:
                print(f"      批改分数: {record.score}")
                if record.marking_content:
                    print(f"      评语: {record.marking_content}")
    print()

2. 获取原卷数据并保存 HTML

import os
from datetime import datetime

# 获取考试和科目信息
page_exam = teacher.get_exams()
if page_exam.exams:
    exam = page_exam.exams[0]
    subjects = teacher.get_exam_subjects(exam.id)
    
    if subjects:
        topic_set_id = subjects[0].id
        subject_name = subjects[0].name
        
        # 学生ID列表（需要从其他途径获取）
        user_ids = ["student_001", "student_002", "student_003"]
        
        # 创建保存目录
        save_dir = f"papers/{exam.name}/{subject_name}"
        os.makedirs(save_dir, exist_ok=True)
        
        for user_id in user_ids:
            # 保存 HTML 文件
            save_path = os.path.join(save_dir, f"{user_id}.html")
            
            # 获取原卷数据并保存 HTML
            original_paper = teacher.get_original_paper(
                user_id, 
                topic_set_id, 
                save_path
            )
            
            print(f"✓ {user_id} - 总分: {original_paper.total_score}")

3. 统计分析原卷数据

# 批量分析学生原卷
user_ids = ["student_001", "student_002", "student_003"]
topic_set_id = "subject_001"

for user_id in user_ids:
    original_paper = teacher.get_original_paper(user_id, topic_set_id)
    
    # 统计优秀答案和典型错误
    excellent_count = sum(
        1 for d in original_paper.answer_details if d.is_excellent
    )
    error_count = sum(
        1 for d in original_paper.answer_details if d.is_typical_error
    )
    
    print(f"学生 {user_id}:")
    print(f"  总分: {original_paper.total_score}")
    print(f"  优秀答案: {excellent_count} 题")
    print(f"  典型错误: {error_count} 题")
    print()

4. 下载答题卡图片

import requests
import os

user_id = "student_123456"
topic_set_id = "subject_001"

original_paper = teacher.get_original_paper(user_id, topic_set_id)

# 下载所有答题卡图片
img_dir = f"answer_sheets/{user_id}"
os.makedirs(img_dir, exist_ok=True)

for i, img_url in enumerate(original_paper.answer_sheet_images, 1):
    response = requests.get(img_url)
    if response.ok:
        img_path = os.path.join(img_dir, f"page_{i}.jpg")
        with open(img_path, 'wb') as f:
            f.write(response.content)
        print(f"✓ 第 {i} 页已保存")

返回示例

学生ID: student_123456
科目ID: subject_001
总分: 135.5

答题卡共 3 页:
  第 1 页: https://www.zhixue.com/image/sheet1.jpg
  第 2 页: https://www.zhixue.com/image/sheet2.jpg
  第 3 页: https://www.zhixue.com/image/sheet3.jpg

答题详情:
题号 1: 一、选择题
  得分: 50.0/50.0
  答案: ABCDA
  是否正确: True

题号 2: 二、填空题
  得分: 30.0/35.0
  答案: 答案内容...
  是否正确: False
    小题 1: 15.0分
      批改教师: 张老师
      批改分数: 15.0
    小题 2: 15.0分
      批改教师: 李老师
      批改分数: 15.0
      评语: 计算过程有误

题号 3: 三、解答题
  得分: 55.5/65.0
  答案: 解答过程...
  是否正确: False