1

docs/故障排查指南.md

@@ -0,0 +1,143 @@
+# 故障排查指南
+
+## 问题：未能提取到成绩信息，共 0 门课程
+
+### 症状
+日志中出现以下警告信息：
+```
+[WARNING] 未能提取到成绩信息，返回原始文本
+[INFO] 成绩无变化（共 0 门课程）
+```
+
+### 可能的原因和解决方案
+
+#### 1. BeautifulSoup 未安装
+**检查方法：**
+```bash
+python3 -c "import bs4; print('BeautifulSoup4 已安装')"
+```
+
+**解决方案：**
+```bash
+pip3 install beautifulsoup4
+# 或
+pip3 install -r requirements.txt
+```
+
+#### 2. 登录会话失效
+**症状：** 日志中可能出现 "检测到登录页面" 的错误
+
+**解决方案：**
+```bash
+# 停止服务
+systemctl stop grade-monitor
+
+# 重新启动服务（会重新登录）
+systemctl start grade-monitor
+```
+
+#### 3. 网页结构变化
+**检查方法：**
+程序会自动保存 HTML 到 `debug_page.html`，查看这个文件：
+```bash
+# 查看 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. 启用调试模式排查
+
+**临时测试（手动运行）：**
+```bash
+cd ~/grade_monitor
+python3 monitor.py --test --debug
+```
+
+**查看详细日志：**
+```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
+```
+
+#### 5. 检查保存的文件
+```bash
+cd ~/grade_monitor
+
+# 查看上次提取的成绩内容
+cat .last_grade_content.txt
+
+# 查看上次保存的 HTML（如果存在）
+cat .last_grade_page.html | head -50
+
+# 查看调试 HTML（出错时自动保存）
+cat debug_page.html | head -50
+```
+
+### 调试流程
+
+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 中的表格结构
+   - 修改 `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. 是否能手动登录并看到成绩页面