增加公平抽取的丰富功能

新增 科目历史记录过滤，支持仅使用当前科目历史记录计算权重，精准锁定学科数据，大幅提升抽取公平性！
新增 课间记录归属，支持将课间时段记录归属到上节课或下节课，灵活适配不同教学节奏！
新增 历史记录课程筛选，支持按课程快速筛选历史记录，一键定位目标数据，效率翻倍！

Author: lzy98276

CHANGELOG/v2.2.0/CHANGELOG.md

@@ -8,9 +8,9 @@ v2.0 - Koharu（小鸟游星野） release 3
 - 新增 **通知渠道**，新增「SecRandom+ClassIsland」选项
 - 新增 **字体粗细设置**，支持9种字体粗细（极细/特细/细体/常规/中等/半粗/粗体/特粗/极粗）
 - 新增 **数量标签显示模式**，支持"总+剩余"、"总数"、"剩余数"、"不显示"四种模式
-- 新增 **科目历史记录过滤**，支持只使用当前科目历史记录计算权重
-- 新增 **课间记录归属**，支持将课间时段记录归属到上节课或下节课
-- 新增 **历史记录课程筛选**，支持按课程查看历史记录
+- 新增 **科目历史记录过滤**，支持仅使用当前科目历史记录计算权重，精准锁定学科数据，大幅提升抽取公平性！
+- 新增 **课间记录归属**，支持将课间时段记录归属到上节课或下节课，灵活适配不同教学节奏！
+- 新增 **历史记录课程筛选**，支持按课程快速筛选历史记录，一键定位目标数据，效率翻倍！
 
 ## 💡 功能优化
 

app/Language/modules/history.py

@@ -296,6 +296,11 @@
             "description": "选择历史记录的查看方式",
             "combo_items": ["全部记录", "按时间查看"],
         },
+        "select_subject": {
+            "name": "选择课程",
+            "description": "选择要查看的课程",
+            "combo_items": ["全部课程"],
+        },
         "HeaderLabels_all_weight": {
             "name": ["序号", "名称", "中奖次数", "权重"],
             "description": "抽奖历史记录表格列标题（全部记录）",
@@ -323,6 +328,11 @@
             "description": "Choose how history is viewed",
             "combo_items": {"0": "All history", "1": "View by time"},
         },
+        "select_subject": {
+            "name": "Select subject",
+            "description": "Choose a subject to view",
+            "combo_items": ["All subjects"],
+        },
         "HeaderLabels_all_weight": {
             "name": {
                 "0": "Serial",

app/common/fair_draw/avg_gap_protection.py

@@ -4,7 +4,7 @@
 
 from typing import List, Dict, Any
 from loguru import logger
-from app.common.history.history import load_history_data
+from app.common.history import *
 from app.tools.settings_access import readme_settings_async
 
 
@@ -81,16 +81,16 @@ def apply_avg_gap_protection(
     draw_count: int,
     class_name: str,
     history_type: str = "roll_call",
+    subject_filter: str = "",
 ) -> List[Dict[str, Any]]:
     """
     应用平均值过滤 + 最大差距保护的公平抽取逻辑
-
     Args:
         candidates: 候选列表，每个元素包含学生信息
         draw_count: 本次要抽取的人数
         class_name: 班级名称
         history_type: 历史记录类型，默认为"roll_call"
-
+        subject_filter: 科目过滤，如果指定则只计算该科目的历史记录
     Returns:
         处理后的候选池
     """
@@ -115,15 +115,32 @@ def apply_avg_gap_protection(
         # Step 1: 获取当前抽取单位的次数
         # 加载历史记录
         history_data = load_history_data(history_type, class_name)
-
         # 初始化学生抽取次数字典
         student_counts = {}
         for student in candidates:
             student_name = _get_student_name(student)
             if student_name:
                 # 从历史记录中获取该学生的抽取次数
                 student_history = history_data.get("students", {}).get(student_name, {})
-                student_counts[student_name] = student_history.get("total_count", 0)
+
+                # 如果有科目过滤，使用科目统计
+                if subject_filter and history_type == "roll_call":
+                    subject_stats = student_history.get("subject_stats", {})
+                    if subject_filter in subject_stats:
+                        student_counts[student_name] = subject_stats[
+                            subject_filter
+                        ].get("total_count", 0)
+                    else:
+                        # 如果科目统计中没有该科目，从历史记录中计算
+                        history = student_history.get("history", [])
+                        filtered_count = 0
+                        for record in history:
+                            if record.get("class_name", "") == subject_filter:
+                                filtered_count += 1
+                        student_counts[student_name] = filtered_count
+                else:
+                    # 没有科目过滤，使用总次数
+                    student_counts[student_name] = student_history.get("total_count", 0)
 
         # 获取所有学生的抽取次数列表
         counts = list(student_counts.values())

app/common/history/__init__.py

@@ -0,0 +1,94 @@
+# ==================================================
+# 历史记录模块
+# ==================================================
+# 该模块提供历史记录的保存、加载、统计和权重计算功能
+
+# 文件工具
+from app.common.history.file_utils import (
+    get_history_file_path,
+    load_history_data,
+    save_history_data,
+    get_all_history_names,
+)
+
+# 统计函数
+from app.common.history.statistics import (
+    get_name_history,
+    get_draw_sessions_history,
+    get_individual_statistics,
+)
+
+# 抽奖历史
+from app.common.history.lottery_history import save_lottery_history
+
+# 点名历史
+from app.common.history.roll_call_history import save_roll_call_history
+
+# 权重工具
+from app.common.history.weight_utils import (
+    format_weight_for_display,
+    calculate_weight,
+)
+
+# 辅助函数
+from app.common.history.utils import (
+    get_all_names,
+    format_table_item,
+    create_table_item,
+)
+
+# 历史记录读取工具
+from app.common.history.history_reader import (
+    # 点名历史读取
+    get_roll_call_student_list,
+    get_roll_call_history_data,
+    filter_roll_call_history_by_subject,
+    get_roll_call_student_total_count,
+    get_roll_call_students_data,
+    get_roll_call_session_data,
+    get_roll_call_student_stats_data,
+    check_class_has_gender_or_group,
+    # 抽奖历史读取
+    get_lottery_pool_list,
+    get_lottery_history_data,
+    get_lottery_prizes_data,
+    get_lottery_session_data,
+    get_lottery_prize_stats_data,
+)
+
+__all__ = [
+    # 文件工具
+    "get_history_file_path",
+    "load_history_data",
+    "save_history_data",
+    "get_all_history_names",
+    # 统计函数
+    "get_name_history",
+    "get_draw_sessions_history",
+    "get_individual_statistics",
+    # 抽奖历史
+    "save_lottery_history",
+    # 点名历史
+    "save_roll_call_history",
+    # 权重工具
+    "format_weight_for_display",
+    "calculate_weight",
+    # 辅助函数
+    "get_all_names",
+    "format_table_item",
+    "create_table_item",
+    # 历史记录读取工具
+    "get_roll_call_student_list",
+    "get_roll_call_history_data",
+    "filter_roll_call_history_by_subject",
+    "get_roll_call_student_total_count",
+    "get_roll_call_students_data",
+    "get_roll_call_session_data",
+    "get_roll_call_student_stats_data",
+    "check_class_has_gender_or_group",
+    "get_lottery_pool_list",
+    "get_lottery_history_data",
+    "get_lottery_prizes_data",
+    "get_lottery_session_data",
+    "get_lottery_prize_stats_data",
+]

app/common/history/file_utils.py

@@ -0,0 +1,99 @@
+# ==================================================
+# 导入库
+# ==================================================
+import json
+from typing import Dict, List, Any
+from pathlib import Path
+
+from loguru import logger
+
+from app.tools.path_utils import get_path
+
+
+# ==================================================
+# 历史记录文件路径处理函数
+# ==================================================
+def get_history_file_path(history_type: str, file_name: str) -> Path:
+    """获取历史记录文件路径
+
+    Args:
+        history_type: 历史记录类型 (roll_call, lottery 等)
+        file_name: 文件名（不含扩展名）
+
+    Returns:
+        Path: 历史记录文件路径
+    """
+    history_dir = get_path(f"data/history/{history_type}_history")
+    history_dir.mkdir(parents=True, exist_ok=True)
+    return history_dir / f"{file_name}.json"
+
+
+# ==================================================
+# 历史记录数据读写函数
+# ==================================================
+
+
+def load_history_data(history_type: str, file_name: str) -> Dict[str, Any]:
+    """加载历史记录数据
+
+    Args:
+        history_type: 历史记录类型 (roll_call, lottery 等)
+        file_name: 文件名（不含扩展名）
+
+    Returns:
+        Dict[str, Any]: 历史记录数据
+    """
+    file_path = get_history_file_path(history_type, file_name)
+
+    if not file_path.exists():
+        return {}
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        logger.error(f"加载历史记录数据失败: {e}")
+        return {}
+
+
+def save_history_data(history_type: str, file_name: str, data: Dict[str, Any]) -> bool:
+    """保存历史记录数据
+
+    Args:
+        history_type: 历史记录类型 (roll_call, lottery 等)
+        file_name: 文件名（不含扩展名）
+        data: 要保存的数据
+
+    Returns:
+        bool: 保存是否成功
+    """
+    file_path = get_history_file_path(history_type, file_name)
+    try:
+        with open(file_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=4)
+        return True
+    except Exception as e:
+        logger.error(f"保存历史记录数据失败: {e}")
+    return False
+
+
+def get_all_history_names(history_type: str) -> List[str]:
+    """获取所有历史记录名称列表
+
+    Args:
+        history_type: 历史记录类型 (roll_call, lottery 等)
+
+    Returns:
+        List[str]: 历史记录名称列表
+    """
+    try:
+        history_dir = get_path(f"data/history/{history_type}_history")
+        if not history_dir.exists():
+            return []
+        history_files = list(history_dir.glob("*.json"))
+        names = [file.stem for file in history_files]
+        names.sort()
+        return names
+    except Exception as e:
+        logger.error(f"获取历史记录名称列表失败: {e}")
+        return []