GPA_Monitoring/docs/故障排查指南.md

故障排查指南

问题：未能提取到成绩信息，共 0 门课程

症状

日志中出现以下警告信息：

[WARNING] 未能提取到成绩信息，返回原始文本
[INFO] 成绩无变化（共 0 门课程）

可能的原因和解决方案

1. BeautifulSoup 未安装

检查方法：

python3 -c "import bs4; print('BeautifulSoup4 已安装')"

解决方案：

pip3 install beautifulsoup4
# 或
pip3 install -r requirements.txt

2. 登录会话失效

症状： 日志中可能出现 "检测到登录页面" 的错误

解决方案：

# 停止服务
systemctl stop grade-monitor

# 重新启动服务（会重新登录）
systemctl start grade-monitor

3. 网页结构变化

检查方法： 程序会自动保存 HTML 到 debug_page.html，查看这个文件：

# 查看 debug_page.html 是否存在
ls -la ~/grade_monitor/debug_page.html

# 查看 HTML 内容，确认是否有成绩表格
grep -i "gridtable\|课程名称\|成绩" ~/grade_monitor/debug_page.html

解决方案： 如果网页结构变化，可能需要修改 monitor.py 中的 extract_grade_info 函数。 当前支持的表格选择器：

• <table class="gridtable">
• <table id="dataList">
• 任何包含"课程名称"或"成绩"关键词的表格

4. 启用调试模式排查

临时测试（手动运行）：

cd ~/grade_monitor
python3 monitor.py --test --debug

查看详细日志：

# 启用调试模式修改服务配置
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

5. 检查保存的文件

cd ~/grade_monitor

# 查看上次提取的成绩内容
cat .last_grade_content.txt

# 查看上次保存的 HTML（如果存在）
cat .last_grade_page.html | head -50

# 查看调试 HTML（出错时自动保存）
cat debug_page.html | head -50

调试流程

1. 启用调试模式运行一次测试：

   cd ~/grade_monitor
   python3 monitor.py --test --debug
   

2. 查看输出信息：

   • 是否显示 "找到成绩表格"？
   • 是否显示 "找到 X 行成绩数据"？
   • 是否显示 "共解析到 X 门课程"？

3. 检查保存的文件：

   # 如果生成了 debug_page.html
   ls -lh debug_page.html
   
   # 查看是否包含成绩表格
   grep -A 5 "gridtable\|dataList" debug_page.html
   

4. 如果是网页结构问题：

   • 将 debug_page.html 发给开发者
   • 或者自己检查 HTML 中的表格结构
   • 修改 extract_grade_info 函数中的选择器

常见问题

Q: 日志显示"未找到成绩表格" A: 网页结构可能变化，需要查看 debug_page.html 确认实际的表格结构

Q: 日志显示"找到 0 行成绩数据" A: 表格找到了但是为空，可能是：

• 登录失效，返回的是空表格
• 实际就是没有成绩数据

Q: 日志显示"检测到未解析的HTML内容" A: BeautifulSoup 解析失败，返回了原始 HTML。检查：

1. BeautifulSoup 是否正确安装
2. HTML 格式是否正确（查看 debug_page.html）

联系支持

如果以上方法都无法解决问题，请提供：

1. monitor.log 的最后 50 行
2. debug_page.html 文件（如果存在）
3. .last_grade_content.txt 文件内容
4. 是否能手动登录并看到成绩页面