1

docs/BUG修复_邮件课程列表不正确.md

@@ -0,0 +1,213 @@
+# BUG修复：邮件通知课程列表不正确
+
+## 问题描述
+
+**症状：**
+- 日志显示检测到2门新增课程：
+  - 马克思主义基本原理 (A3505000018)
+  - 软件需求分析与设计 (A0801050220)
+
+- 但邮件通知显示的是3门**完全不同**的课程：
+  - C++程序设计
+  - 体育(三) 乒乓球
+  - 概率论与数理统计
+
+## 根本原因
+
+代码逻辑错误：
+
+```python
+# 错误的实现
+if self.check_grade_changes(grade_info, grade_html):
+    courses_file = self.script_dir / '.last_courses.txt'
+    if courses_file.exists():
+        # ❌ 发送的是当前所有课程的前3门，而不是新增课程
+        self.send_email_notification(current_courses[:3])
+```
+
+### 问题分析
+
+1. `check_grade_changes` 函数内部计算了新增课程列表 `new_courses`
+2. 但函数只返回 `True/False`，**没有返回新增课程列表**
+3. 主循环中使用了 `current_courses[:3]`（当前所有课程的前3门）
+4. 导致邮件中显示的课程与实际新增的课程不一致
+
+### 举例说明
+
+**场景：**
+- 之前有6门课程：A、B、C、D、E、F
+- 新增2门课程：G、H
+- 当前总共8门课程：A、B、C、D、E、F、G、H
+
+**错误行为：**
+- 日志显示：新增2门（G、H）✓ 正确
+- 邮件显示：A、B、C（前3门）❌ 错误
+
+**期望行为：**
+- 邮件显示：G、H ✓ 正确
+
+## 修复方案
+
+### 1. 修改 `check_grade_changes` 函数签名
+
+```python
+# 修改前
+def check_grade_changes(self, current_content: str, current_html: str = None) -> bool:
+
+# 修改后
+def check_grade_changes(self, current_content: str, current_html: str = None) -> tuple:
+    """检查成绩是否有变化
+    
+    Returns:
+        tuple: (是否有变化: bool, 新增课程列表: list)
+    """
+```
+
+### 2. 返回新增课程列表
+
+```python
+# 修改前
+if new_courses:
+    # ... 记录日志 ...
+    return True
+
+# 修改后
+if new_courses:
+    # ... 记录日志 ...
+    return (True, new_courses)  # 返回元组
+
+# 其他情况
+return (False, [])  # 无变化
+return (True, [])   # 有变化但无新增课程（成绩更新）
+```
+
+### 3. 更新调用代码
+
+```python
+# 修改前
+if self.check_grade_changes(grade_info, grade_html):
+    self.send_email_notification(current_courses[:3])  # ❌ 错误
+
+# 修改后
+has_changes, new_courses = self.check_grade_changes(grade_info, grade_html)
+
+if has_changes:
+    if new_courses:
+        # 有新增课程，发送真正的新增课程列表
+        self.send_email_notification(new_courses)  # ✅ 正确
+    else:
+        # 没有新增课程但内容变化（成绩更新），发送通用通知
+        self.send_email_notification()
+```
+
+## 修复效果
+
+### 修复前
+```
+日志：
+[INFO] ✓ 检测到新增课程成绩！共 2 门
+[INFO]   1. [2025-2026 秋季] 马克思主义基本原理 (A3505000018)
+[INFO]   2. [2025-2026 秋季] 软件需求分析与设计 (A0801050220)
+
+邮件：
+新增课程（共3门）：
+  - 2025-2026 秋季 C++程序设计          ❌ 错误！
+  - 2025-2026 秋季 体育(三) 乒乓球      ❌ 错误！
+  - 2025-2026 秋季 概率论与数理统计     ❌ 错误！
+```
+
+### 修复后
+```
+日志：
+[INFO] ✓ 检测到新增课程成绩！共 2 门
+[INFO]   1. [2025-2026 秋季] 马克思主义基本原理 (A3505000018)
+[INFO]   2. [2025-2026 秋季] 软件需求分析与设计 (A0801050220)
+
+邮件：
+新增课程（共2门）：
+  - 2025-2026 秋季 马克思主义基本原理   ✅ 正确！
+  - 2025-2026 秋季 软件需求分析与设计   ✅ 正确！
+```
+
+## 测试建议
+
+### 1. 单元测试场景
+
+**场景1：新增课程**
+- 之前：3门课程
+- 现在：5门课程（新增2门）
+- 期望：邮件显示新增的2门
+
+**场景2：成绩更新**
+- 之前：5门课程
+- 现在：5门课程（某门成绩变化）
+- 期望：邮件显示通用通知
+
+**场景3：无变化**
+- 之前：5门课程
+- 现在：5门课程（完全相同）
+- 期望：不发送邮件
+
+### 2. 集成测试
+
+```bash
+# 1. 删除历史记录（模拟首次运行）
+cd ~/grade_monitor
+rm .last_*
+
+# 2. 运行测试
+python3 monitor.py --test
+
+# 3. 再次运行（模拟检测到变化）
+# 手动编辑 .last_courses.txt，删除几行
+python3 monitor.py --test
+
+# 4. 检查邮件内容是否正确
+```
+
+## 影响评估
+
+### 向后兼容性
+- ✅ 完全兼容：函数返回元组，Python 会自动解包
+- ✅ 不影响测试模式：test_fetch 不调用此函数
+- ✅ 不影响旧版数据：历史文件格式不变
+
+### 风险等级
+- 🟢 **低风险**：仅修改返回值类型
+- 🟢 所有调用点已更新
+- 🟢 已通过语法检查
+
+## 部署步骤
+
+```bash
+# 1. 本地打包
+cd /mnt/e/50425/Documents/Github/GPA_Monitoring
+./打包.sh
+
+# 2. 上传到服务器
+scp gpa_monitor.tar.gz user@server:~/
+
+# 3. 服务器上更新
+systemctl stop grade-monitor
+cd ~/grade_monitor
+cp monitor.py monitor.py.backup.$(date +%Y%m%d_%H%M%S)
+tar -xzf ~/gpa_monitor.tar.gz
+systemctl restart grade-monitor
+
+# 4. 验证
+tail -f monitor.log
+```
+
+## 后续优化建议
+
+1. **添加单元测试** - 测试 `check_grade_changes` 函数
+2. **记录邮件内容** - 在日志中记录发送的课程列表
+3. **邮件确认机制** - 发送成功后记录一份副本
+
+---
+
+**BUG编号：** #001  
+**严重程度：** 高（数据不一致）  
+**修复日期：** 2026-01-21  
+**修复人员：** GitHub Copilot  
+**测试状态：** 待用户验证