创建完整使用文档.md

2026-01-29 04:45:15 +08:00
parent 2e0e4ea8c6
commit 4c41df3e39
1 changed files with 996 additions and 0 deletions
--- a/docs/完整使用文档.md
+++ b/docs/完整使用文档.md
@@ -0,0 +1,996 @@
 # 成绩监控系统 - 完整使用文档
 > **最后更新：** 2026-01-29  
 > **版本：** v2.0 - 自动会话恢复版
 ---
 ## 📑 目录
 1. [服务器部署指南](#服务器部署指南)
 2. [快速更新指南](#快速更新指南)
 3. [故障排查指南](#故障排查指南)
 4. [常见问题解决](#常见问题解决)
 5. [服务管理](#服务管理)
 6. [历史BUG修复记录](#历史bug修复记录)
 ---
 # 服务器部署指南
 ## 📋 前置要求
 - Linux服务器（Debian/Ubuntu/CentOS等）
 - Python 3.7+
 - 服务器能访问外网
 - SSH访问权限
 ## 📦 项目文件说明
 ### 必需文件（需要上传到服务器）
 | 文件名 | 用途 | 何时使用 |
 |--------|------|----------|
 | `monitor.py` | **主程序** | 运行监控的核心文件 |
 | `config.ini` | **配置文件** | 包含账号密码、邮箱配置（⚠️ 敏感文件） |
 | `requirements.txt` | **Python依赖列表** | 安装Python包时使用 |
 | `setup_python.sh` | **环境安装脚本** | 首次部署时执行，安装所有依赖 |
 | `grade-monitor.service` | **systemd服务配置** | 设置开机自启和后台运行 |
 ### 可选文件（参考文档）
 | 文件名 | 用途 |
 |--------|------|
 | `config（模板）.ini` | 配置文件模板，新用户参考 |
 | `README.md` | 项目说明文档 |
 | `diagnose.sh` | 故障诊断脚本 |
 ### 不需要的文件（不要上传）
 - `venv/` - 虚拟环境（服务器上重新创建）
 - `.git/` - Git仓库（可选）
 - `.last_*` - 运行时生成的缓存文件
 - `monitor.log` - 运行时生成的日志文件
 ## 🚀 部署步骤
 ### 第一步：准备文件
 ```bash
 # 在本地打包必需文件（WSL或Git Bash）
 cd /mnt/e/50425/Documents/Github/GPA_Monitoring
 # 创建压缩包（只包含必需文件）
 tar -czf gpa_monitor.tar.gz \
    monitor.py \
    config.ini \
    requirements.txt \
    setup_python.sh \
    diagnose.sh \
    grade-monitor.service \
    README.md
 # 查看压缩包内容
 tar -tzf gpa_monitor.tar.gz
 ```
 ### 第二步：上传到服务器
 ```bash
 # 方法1：使用 scp
 scp gpa_monitor.tar.gz 用户名@服务器IP:/home/用户名/
 # 方法2：使用 rsync（推荐）
 rsync -avz gpa_monitor.tar.gz 用户名@服务器IP:/home/用户名/
 # 方法3：使用 sftp
 sftp 用户名@服务器IP
 put gpa_monitor.tar.gz
 exit
 ```
 ### 第三步：在服务器上解压并安装
 ```bash
 # 登录到服务器
 ssh 用户名@服务器IP
 # 解压文件
 cd ~
 tar -xzf gpa_monitor.tar.gz
 cd grade_monitor  # 或者你解压到的目录
 # 给脚本添加执行权限
 chmod +x setup_python.sh diagnose.sh
 # 运行安装脚本（会自动安装Python、创建虚拟环境、安装依赖）
 ./setup_python.sh
 ```
 ### 第四步：检查配置文件
 ```bash
 # 编辑配置文件（如果需要修改）
 nano config.ini
 # 确认配置正确：
 # - USERNAME 和 PASSWORD（学号和密码）
 # - 邮箱配置（SENDER_EMAIL、SENDER_PASSWORD、RECEIVER_EMAIL）
 # - CHECK_INTERVAL（建议120秒以上）
 ```
 配置文件示例：
 ```ini
 [login]
 USERNAME = 你的学号
 PASSWORD = 你的密码
 LOGIN_URL = ...
 GRADE_URL = ...
 [email]
 SENDER_EMAIL = your_email@163.com
 SENDER_PASSWORD = SMTP授权码（不是邮箱密码！）
 RECEIVER_EMAIL = 接收通知的邮箱
 [monitor]
 CHECK_INTERVAL = 120  # 建议120-300秒
 REQUEST_DELAY = 5
 MAX_RETRIES = 3
 RETRY_DELAY = 10
 ```
 ### 第五步：测试运行
 ```bash
 # 激活虚拟环境
 source venv/bin/activate
 # 测试运行（获取一次成绩，不进行监控）
 python3 monitor.py --test
 # 查看提取的成绩
 cat .last_grade_content.txt
 ```
 ## 🔧 设置后台运行
 ### 方案A：使用 systemd（推荐，生产环境）
 **优点：** 开机自启、崩溃自动重启、系统化管理
 ```bash
 # 1. 编辑服务文件，修改用户名和路径
 nano grade-monitor.service
 # 确保这些路径正确：
 # User=你的用户名
 # WorkingDirectory=/home/你的用户名/grade_monitor
 # ExecStart=/home/你的用户名/grade_monitor/venv/bin/python3 /home/你的用户名/grade_monitor/monitor.py
 # 2. 复制服务文件到系统目录
 sudo cp grade-monitor.service /etc/systemd/system/
 # 3. 重新加载 systemd
 sudo systemctl daemon-reload
 # 4. 启动服务
 sudo systemctl start grade-monitor
 # 5. 查看状态
 sudo systemctl status grade-monitor
 # 6. 设置开机自启
 sudo systemctl enable grade-monitor
 ```
 **systemd 常用命令：**
 ```bash
 # 启动
 sudo systemctl start grade-monitor
 # 停止
 sudo systemctl stop grade-monitor
 # 重启
 sudo systemctl restart grade-monitor
 # 查看状态
 sudo systemctl status grade-monitor
 # 查看日志
 sudo journalctl -u grade-monitor -f
 # 开机自启
 sudo systemctl enable grade-monitor
 # 禁用自启
 sudo systemctl disable grade-monitor
 ```
 ### 方案B：使用 tmux（简单易用）
 **优点：** 简单、可随时查看输出、适合测试阶段
 ```bash
 # 1. 安装 tmux（如果没有）
 sudo apt update && sudo apt install tmux
 # 2. 创建会话并运行
 tmux new -s grade_monitor
 source venv/bin/activate
 python3 monitor.py
 # 3. 离开会话（程序继续运行）
 # 按 Ctrl+B，然后按 D
 # 4. 重新连接查看
 tmux attach -t grade_monitor
 # 5. 查看所有会话
 tmux ls
 # 6. 关闭会话
 tmux kill-session -t grade_monitor
 ```
 ### 方案C：使用 nohup（最简单）
 **优点：** 快速、无需额外工具
 ```bash
 # 后台运行
 source venv/bin/activate
 nohup python3 monitor.py > output.log 2>&1 &
 # 查看进程
 ps aux | grep monitor.py
 # 停止程序
 pkill -f monitor.py
 ```
 ## 📊 监控和维护
 ### 查看日志
 ```bash
 # 查看监控日志（程序自己的日志）
 tail -f ~/grade_monitor/monitor.log
 # 查看最后100行
 tail -n 100 ~/grade_monitor/monitor.log
 # 搜索关键词
 grep "新增课程" ~/grade_monitor/monitor.log
 # 查看系统日志（如果用systemd）
 sudo journalctl -u grade-monitor -f
 sudo journalctl -u grade-monitor --since "1 hour ago"
 ```
 ### 检查运行状态
 ```bash
 # 方法1：查看进程
 ps aux | grep monitor.py
 # 方法2：查看日志时间戳
 ls -lh ~/grade_monitor/monitor.log
 # 方法3：systemd状态（如果用systemd）
 sudo systemctl status grade-monitor
 ```
 ## 🔒 安全建议
 ### 1. 保护配置文件
 ```bash
 # 设置文件权限（只有所有者可读写）
 chmod 600 config.ini
 # 查看权限
 ls -l config.ini
 # 应该显示：-rw------- 1 用户名 用户名
 ```
 ### 2. 不要上传敏感文件到 GitHub
 在 `.gitignore` 中添加：
 ```
 config.ini
 *.log
 .last_*
 venv/
 ```
 ### 3. 定期检查日志
 ```bash
 # 检查是否有异常
 grep -i "error\|fail\|warning" monitor.log
 # 检查登录情况
 grep "登录" monitor.log | tail -20
 ```
 ---
 # 快速更新指南
 ## 🎯 本功能解决的问题
 **症状：** 程序运行几小时后出现：
 ```
 [WARNING] 未能提取到成绩信息，返回原始文本
 [INFO] 成绩无变化（共 0 门课程）
 ```
 **原因：** 登录会话过期，需要重新登录
 **解决：** ✅ 最新版本已自动检测并重新登录
 ## 📦 更新方式
 ### 方式1：完整更新（推荐）
 #### 在本地准备
 ```bash
 # WSL或Git Bash中
 cd /mnt/e/50425/Documents/Github/GPA_Monitoring
 # 创建更新包
 tar -czf gpa_monitor.tar.gz \
    monitor.py \
    config.ini \
    requirements.txt \
    setup_python.sh \
    diagnose.sh \
    grade-monitor.service
 ```
 #### 上传到服务器
 ```bash
 scp gpa_monitor.tar.gz 用户名@服务器IP:~/
 ```
 #### 在服务器上更新
 ```bash
 # 停止服务
 systemctl stop grade-monitor
 # 备份旧文件
 cd ~/grade_monitor
 cp monitor.py monitor.py.backup.$(date +%Y%m%d)
 # 解压更新（会覆盖旧文件）
 tar -xzf ~/gpa_monitor.tar.gz -C ~/grade_monitor
 # 赋予执行权限
 chmod +x diagnose.sh
 # 重启服务
 systemctl restart grade-monitor
 # 查看日志（确认自动重新登录功能）
 tail -f monitor.log
 ```
 ### 方式2：仅更新主程序
 如果只想更新 monitor.py：
 ```bash
 # 在本地（WSL）
 cd /mnt/e/50425/Documents/Github/GPA_Monitoring
 scp monitor.py 用户名@服务器IP:~/grade_monitor/
 # 在服务器上
 systemctl stop grade-monitor
 systemctl start grade-monitor
 tail -f ~/grade_monitor/monitor.log
 ```
 ## ✅ 验证更新成功
 查看日志，应该能看到：
 ### 正常运行
 ```
 [INFO] 开始新一轮检查
 [INFO] 获取成绩页面...
 [DEBUG] 找到成绩表格
 [INFO] 成功提取成绩信息，共 17 行
 [INFO] 共解析到 15 门课程
 [INFO] 成绩无变化（共 15 门课程）
 ```
 ### 会话过期时自动处理
 ```
 [WARNING] 检测到会话过期，尝试重新登录...
 [INFO] 开始登录统一身份认证...
 [INFO] 登录成功！成功访问成绩页面
 [INFO] 重新登录成功，继续监控
 ```
 ## 💡 最佳实践
 1. **定期检查日志**（每天1-2次即可）
   ```bash
   tail -n 50 ~/grade_monitor/monitor.log
   ```
 2. **不要频繁重启服务**
   - 新版本会自动处理会话过期
   - 只在真正出问题时才重启
 3. **保留备份**
   ```bash
   # 每次更新前都会自动备份
   ls -lh ~/grade_monitor/monitor.py.backup.*
   ```
 4. **合理设置检查间隔**
   - 建议 120-300 秒
   - 避免触发学校系统限流
 ---
 # 故障排查指南
 ## 🚨 问题一："未能提取到成绩信息，共 0 门课程"
 ### 症状
 日志中反复出现：
 ```
 [WARNING] 未能提取到成绩信息，返回原始文本
 [INFO] 成绩无变化（共 0 门课程）
 ```
 ### 快速诊断
 #### 步骤1：运行诊断工具
 ```bash
 cd ~/grade_monitor
 ./diagnose.sh
 ```
 诊断工具会自动：
 - 检查 BeautifulSoup 是否安装
 - 运行测试模式
 - 分析测试结果
 - 提供修复建议
 #### 步骤2：检查 BeautifulSoup 安装
 ```bash
 python3 -c "import bs4; print('BeautifulSoup4 已安装')"
 ```
 如果报错，安装依赖：
 ```bash
 pip3 install beautifulsoup4
 # 或完整安装所有依赖
 pip3 install -r requirements.txt
 ```
 #### 步骤3：使用调试模式
 ```bash
 cd ~/grade_monitor
 python3 monitor.py --test --debug
 ```
 查看输出中是否有：
 - ✅ "找到成绩表格"
 - ✅ "找到 X 行成绩数据"
 - ✅ "共解析到 X 门课程"
 #### 步骤4：检查是否登录失效
 ```bash
 grep "登录页面\|LOGIN_REQUIRED" ~/grade_monitor/monitor.log
 ```
 如果有，重启服务重新登录：
 ```bash
 systemctl restart grade-monitor
 ```
 #### 步骤5：查看调试HTML文件
 ```bash
 cd ~/grade_monitor
 # 检查文件是否存在
 ls -lh debug_page.html
 # 查看是否包含成绩表格
 grep -i "gridtable\|课程名称\|成绩" debug_page.html | head -5
 ```
 ### 解决方案
 **方案1：重新安装依赖并重启**
 ```bash
 cd ~/grade_monitor
 pip3 install -r requirements.txt
 systemctl restart grade-monitor
 tail -f monitor.log
 ```
 **方案2：启用调试模式监控**
 ```bash
 # 编辑服务配置
 sudo nano /etc/systemd/system/grade-monitor.service
 # 修改 ExecStart 行添加 --debug 参数
 ExecStart=/usr/bin/python3 /home/yourusername/grade_monitor/monitor.py --debug
 # 重新加载并重启
 sudo systemctl daemon-reload
 sudo systemctl restart grade-monitor
 tail -f ~/grade_monitor/monitor.log
 ```
 **方案3：如果是会话过期**
 最新版本会自动处理！代码会：
 1. 检测到 "LOGIN_REQUIRED" 时自动重新登录
 2. 记录日志：`[WARNING] 检测到会话过期，尝试重新登录...`
 3. 重新登录后继续监控
 **方案4：如果是网页结构变化**
 程序会自动保存 HTML 到 `debug_page.html`，查看这个文件：
 ```bash
 # 查看 HTML 内容，确认是否有成绩表格
 cat debug_page.html | grep -i "gridtable\|dataList" -A 10
 ```
 当前支持的表格选择器：
 - `<table class="gridtable">`
 - `<table id="dataList">`
 - 任何包含"课程名称"或"成绩"关键词的表格
 ## ⚠️ 问题二："请不要过快点击"错误
 ### 问题原因
 学校WebVPN系统有严格的访问频率限制，短时间内多次访问会被拦截。
 ### 解决方案
 #### 1. 停止手动测试至少5分钟
 ```bash
 # 如果在服务器上运行，请先停止程序
 ps aux | grep monitor.py
 kill <进程ID>
 # 等待至少5分钟后再重新测试
 ```
 #### 2. 修改配置文件增加间隔
 ```bash
 nano config.ini
 ```
 修改为：
 ```ini
 [monitor]
 # 将检查间隔改为5分钟（300秒）或更长
 CHECK_INTERVAL = 300
 # 增加请求延迟
 REQUEST_DELAY = 15
 # 增加重试间隔
 RETRY_DELAY = 60
 ```
 #### 3. 使用正确的测试方式
 ```bash
 # 测试前确保距离上次测试至少5分钟
 python3 monitor.py --test
 # 如果还是被拦截，等10分钟后再试
 ```
 #### 4. 部署后不要频繁测试
 ```bash
 # 部署systemd服务后，让它自动运行
 sudo systemctl start grade-monitor
 # 只通过日志查看运行情况
 tail -f monitor.log
 # 不要反复启停服务或手动测试
 ```
 ## 🔍 如何判断系统正常工作
 ### 方法1：查看日志
 ```bash
 tail -f ~/grade_monitor/monitor.log
 ```
 正常日志应该类似：
 ```
 2026-01-29 10:00:00 - INFO - 开始检查成绩变化...
 2026-01-29 10:00:05 - INFO - 登录成功！
 2026-01-29 10:00:10 - INFO - 成功获取成绩页面
 2026-01-29 10:00:12 - INFO - 未发现新课程
 2026-01-29 10:02:00 - INFO - 等待下次检查...
 ```
 ### 方法2：查看保存的成绩文件
 ```bash
 cat ~/.last_grade_content.txt
 ```
 如果文件包含完整的课程列表和GPA，说明系统工作正常。
 ### 方法3：查看进程状态
 ```bash
 ps aux | grep monitor.py
 ```
 如果有进程在运行，说明程序正在监控中。
 ## 📝 调试流程
 1. **启用调试模式运行一次测试：**
   ```bash
   cd ~/grade_monitor
   python3 monitor.py --test --debug
   ```
 2. **查看输出信息：**
   - 是否显示 "找到成绩表格"？
   - 是否显示 "找到 X 行成绩数据"？
   - 是否显示 "共解析到 X 门课程"？
 3. **检查保存的文件：**
   ```bash
   # 如果生成了 debug_page.html
   ls -lh debug_page.html
   # 查看是否包含成绩表格
   grep -A 5 "gridtable\|dataList" debug_page.html
   ```
 4. **如果是网页结构问题：**
   - 将 `debug_page.html` 发给开发者
   - 或者自己检查 HTML 中的表格结构
 ---
 # 常见问题解决
 ## 💡 最佳实践
 ### 测试阶段
 1. **首次测试**：运行 `python3 monitor.py --test`
 2. **等待5分钟**
 3. **再次测试**：确认能正常获取成绩
 4. **等待10分钟**
 5. **部署服务**：配置systemd或使用tmux
 ### 运行阶段
 1. **设置CHECK_INTERVAL为120秒或更长**
 2. **让程序自动运行，不要手动干预**
 3. **每天查看一次日志即可**
 4. **不要频繁重启服务**
 ### 如果被持续拦截
 1. **停止所有监控程序**
 2. **等待至少30分钟**
 3. **将CHECK_INTERVAL改为600秒（10分钟）**
 4. **重新启动，让它慢慢运行**
 5. **确认稳定后，再逐步减少间隔**
 ## 🛠️ 调试技巧
 ### 查看实际响应内容
 ```bash
 cat ~/grade_monitor/.debug_response.html
 ```
 如果文件包含"请不要过快点击"，说明请求被拦截。
 ### 检查登录状态
 ```bash
 # 运行测试模式
 python3 monitor.py --test
 # 查看是否成功登录
 grep "登录成功" monitor.log
 ```
 ### 测试网络连接
 ```bash
 # 测试是否能访问学校网站
 curl -I https://webvpn.neu.edu.cn
 # 测试SMTP邮件服务器
 nc -zv smtp.163.com 465
 ```
 ## 🔧 常见问题FAQ
 ### Q1: 如何确认程序在运行？
 ```bash
 # 方法1：查看进程
 ps aux | grep monitor.py
 # 方法2：查看日志最后几行
 tail monitor.log
 # 方法3：查看文件修改时间
 ls -lh monitor.log
 ```
 ### Q2: 程序报错"请不要过快点击"怎么办？
 编辑配置文件，增加检查间隔：
 ```bash
 nano config.ini
 # 修改 CHECK_INTERVAL 为更大的值（如300秒）
 ```
 ### Q3: 如何在多台服务器部署？
 每台服务器重复部署步骤，注意：
 1. 每台服务器使用不同的监控账号（如果可能）
 2. 适当增加 CHECK_INTERVAL 避免同时访问
 3. 可以设置不同的邮件接收地址
 ### Q4: 忘记 tmux 会话名怎么办？
 ```bash
 # 列出所有会话
 tmux ls
 # 连接到第一个会话
 tmux attach
 ```
 ### Q5: 邮件发送失败怎么办？
 - 确认SMTP授权码正确（不是邮箱密码）
 - 检查服务器能否访问smtp.163.com（端口465）
 - 查看详细错误信息：`tail -f monitor.log`
 ```bash
 # 测试网络连接
 telnet smtp.163.com 465
 # 或
 nc -zv smtp.163.com 465
 ```
 ### Q6: 权限不足怎么办？
 ```bash
 # 修改文件所有者
 sudo chown -R username:username ~/grade_monitor
 # 修改执行权限
 chmod +x ~/grade_monitor/*.sh
 ```
 ## 💬 温馨提示
 1. **成绩更新频率不高**：学校不会每分钟更新成绩，建议CHECK_INTERVAL设为120-300秒
 2. **避免过度监控**：频繁访问可能被学校系统封禁IP
 3. **合理设置间隔**：既能及时发现新成绩，又不会触发限流
 4. **信任自动化**：部署后让程序自己运行，不需要频繁检查
 ---
 # 服务管理
 ## 🔄 重启服务
 ### 使用 systemd
 ```bash
 # 停止服务
 systemctl stop grade-monitor
 # 备份旧文件
 cd ~/grade_monitor
 cp monitor.py monitor.py.backup
 # 如果需要更新文件
 # tar -xzf ~/gpa_monitor.tar.gz -C ~/grade_monitor
 # 重启服务
 systemctl restart grade-monitor
 # 查看实时日志
 tail -f monitor.log
 # 或查看最近的日志（包含完整上下文）
 tail -n 100 monitor.log
 ```
 ### 使用 tmux
 ```bash
 # 连接到会话
 tmux attach -t grade_monitor
 # 停止程序（Ctrl+C）
 # 重新运行
 source venv/bin/activate
 python3 monitor.py
 # 离开会话（Ctrl+B 然后 D）
 ```
 ### 使用 nohup
 ```bash
 # 查找进程
 ps aux | grep monitor.py
 # 停止进程
 kill <进程ID>
 # 重新启动
 cd ~/grade_monitor
 source venv/bin/activate
 nohup python3 monitor.py > output.log 2>&1 &
 ```
 ## 📊 日志查看
 ### 查看监控日志
 ```bash
 # 实时查看
 tail -f ~/grade_monitor/monitor.log
 # 查看最后N行
 tail -n 50 ~/grade_monitor/monitor.log
 # 搜索关键词
 grep "新增课程\|错误\|warning" ~/grade_monitor/monitor.log
 ```
 ### 查看系统日志（systemd）
 ```bash
 # 实时查看
 sudo journalctl -u grade-monitor -f
 # 查看最近1小时
 sudo journalctl -u grade-monitor --since "1 hour ago"
 # 查看今天的日志
 sudo journalctl -u grade-monitor --since today
 ```
 ## 🔍 状态检查
 ```bash
 # 检查服务状态（systemd）
 sudo systemctl status grade-monitor
 # 检查进程
 ps aux | grep monitor.py
 # 检查最后一次检查时间
 ls -lh ~/grade_monitor/monitor.log
 # 查看保存的成绩
 cat ~/grade_monitor/.last_grade_content.txt
 ```
 ## 📦 完整更新流程
 ```bash
 # 1. 在本地打包
 cd /mnt/e/50425/Documents/Github/GPA_Monitoring
 tar -czf gpa_monitor.tar.gz monitor.py config.ini requirements.txt setup_python.sh
 # 2. 上传到服务器
 scp gpa_monitor.tar.gz user@server:~/
 # 3. 在服务器上更新
 ssh user@server
 systemctl stop grade-monitor
 cd ~/grade_monitor
 cp monitor.py monitor.py.backup.$(date +%Y%m%d)
 tar -xzf ~/gpa_monitor.tar.gz
 systemctl restart grade-monitor
 # 4. 验证
 tail -f monitor.log
 ```
 ---
 # 历史BUG修复记录
 ## BUG #001: 邮件通知课程列表不正确
 **修复日期：** 2026-01-21  
 **严重程度：** 高（数据不一致）  
 **修复状态：** ✅ 已修复
 ### 问题描述
 **症状：**
 - 日志显示检测到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. 导致邮件中显示的课程与实际新增的课程不一致
 ### 修复方案
 1. **修改函数签名**：返回元组 `(是否有变化: bool, 新增课程列表: list)`
 2. **返回新增课程列表**：`return (True, new_courses)`
 3. **更新调用代码**：使用真正的新增课程列表发送邮件
 ### 修复效果
 **修复前：**
 ```
 日志：检测到2门新增课程
 邮件：显示3门完全不同的课程 ❌
 ```
 **修复后：**
 ```
 日志：检测到2门新增课程
 邮件：准确显示这2门新增课程 ✅
 ```
 ---
 ## 📞 获取帮助
 如果遇到问题：
 1. 先运行诊断工具：`./diagnose.sh`
 2. 查看本文档的故障排查部分
 3. 查看 `monitor.log` 了解详细错误
 4. 运行 `python3 monitor.py --test --debug` 测试
 5. 检查 `debug_page.html` 了解实际响应
 ---
 ## ✅ 部署检查清单
 - [ ] 文件已上传到服务器
 - [ ] config.ini配置正确（账号、密码、邮箱）
 - [ ] 运行setup_python.sh安装依赖
 - [ ] 测试模式运行成功
 - [ ] 成绩提取格式正确
 - [ ] 配置后台运行（systemd/tmux）
 - [ ] 服务正常启动
 - [ ] 日志输出正常
 - [ ] 收到测试邮件
 - [ ] 设置文件权限（chmod 600 config.ini）
 ---
 **文档版本：** v2.0  
 **最后更新：** 2026-01-29  
 **维护者：** GitHub Copilot