1

间歇性解析失败说明.md

@@ -0,0 +1,194 @@
+# 间歇性解析失败说明
+
+## 现象
+
+日志显示偶尔出现解析失败，但下一次检查又恢复正常：
+
+```
+17:34:05 - ✅ 成功提取成绩信息，共 14 行，解析到 8 门课程
+17:36:12 - ✅ 成功提取成绩信息，共 14 行，解析到 8 门课程
+17:38:12 - ❌ 未找到成绩表格，解析到 0 门课程
+17:40:12 - ✅ 成功提取成绩信息，共 14 行，解析到 8 门课程
+```
+
+## 原因分析
+
+这种**偶发性失败**通常是由以下原因造成的：
+
+### 1. 网络波动（最常见）
+- 数据包传输不完整
+- HTML内容被截断
+- 连接临时中断
+
+### 2. 服务器临时问题
+- 学校服务器负载高
+- 短暂的维护或重启
+- 数据库查询超时
+
+### 3. WebVPN不稳定
+- WebVPN代理服务波动
+- SSL握手失败
+- 重定向异常
+
+### 4. 时机问题
+- 正好在服务器更新数据时访问
+- 缓存失效瞬间
+- 负载均衡切换
+
+## 改进措施
+
+最新版本已添加**智能容错机制**：
+
+### 1. 识别网络错误
+```python
+# 检查HTML内容长度
+if len(html) < 100:
+    logger.warning(f"HTML内容过短({len(html)}字节)，可能是网络问题")
+    return "NETWORK_ERROR"
+```
+
+### 2. 自动重试
+当检测到临时性问题时：
+- ⚠️ 记录警告但不立即报错
+- ⏱️ 等待30秒后自动重试
+- 📊 只有连续3次失败才报警
+
+### 3. 智能判断
+```python
+# 如果解析到0门课程，但之前有课程记录
+if len(current_courses) == 0 and len(previous_courses) > 0:
+    logger.warning("可能是临时问题，30秒后重试")
+    time.sleep(30)
+    continue  # 重新检查
+```
+
+### 4. 保存诊断信息
+- 自动保存 `debug_page.html`
+- 记录HTML长度和摘要
+- 便于事后分析
+
+## 预期行为
+
+### 场景1：偶发性失败（正常）
+```
+[INFO] 成功提取成绩信息，共 14 行
+[INFO] 共解析到 8 门课程
+[INFO] 等待 120 秒...
+
+[WARNING] 未找到成绩表格
+[WARNING] ⚠️ 解析到0门课程，但之前有8门课程，可能是临时问题
+[INFO] 等待 30 秒后重试...
+
+[INFO] 成功提取成绩信息，共 14 行  ← 重试成功
+[INFO] 共解析到 8 门课程
+```
+
+### 场景2：持续失败（异常）
+```
+[WARNING] ⚠️ 解析到0门课程，可能是临时问题
+[WARNING] 连续异常: 1/5
+
+[WARNING] ⚠️ 解析到0门课程，可能是临时问题
+[WARNING] 连续异常: 2/5
+
+[WARNING] ⚠️ 解析到0门课程，可能是临时问题
+[WARNING] 连续异常: 3/5  ← 开始报警
+
+[ERROR] 连续 3 次无法解析课程（之前有8门课程）
+```
+
+## 判断标准
+
+### ✅ 无需担心的情况
+- 失败率 < 20%（每10次失败少于2次）
+- 失败后1-2次就恢复
+- 日志显示"等待30秒后重试"
+- 下次检查自动恢复正常
+
+### ⚠️ 需要关注的情况
+- 失败率 > 20%
+- 连续3次以上失败
+- 日志显示"连续异常"
+- 出现错误通知邮件
+
+### 🚨 需要处理的情况
+- 连续5次以上失败
+- 失败率 > 50%
+- 伴随"会话过期"错误
+- debug_page.html 显示登录页面
+
+## 统计失败率
+
+使用诊断工具检查：
+```bash
+cd ~/grade_monitor
+./diagnose.sh
+
+# 或手动统计
+echo "成功次数: $(grep -c '共解析到 [1-9]' monitor.log)"
+echo "失败次数: $(grep -c '共解析到 0 门课程' monitor.log)"
+```
+
+## 最佳实践
+
+### 1. 不要过度担心
+- 偶尔失败是**正常现象**
+- 程序已自动处理
+- 只要失败率低，无需干预
+
+### 2. 定期检查日志
+```bash
+# 查看最近的失败记录
+grep "未找到成绩表格\|共解析到 0 门课程" ~/grade_monitor/monitor.log | tail -10
+
+# 查看是否自动恢复
+tail -n 20 ~/grade_monitor/monitor.log
+```
+
+### 3. 调整检查间隔
+如果失败频繁，可以增加间隔：
+```ini
+[monitor]
+CHECK_INTERVAL = 180  # 从120改为180秒
+```
+
+### 4. 信任自动化
+- 程序会自动重试
+- 只有持续失败才报警
+- 收到邮件通知时再处理
+
+## 何时需要手动干预
+
+只在以下情况需要重启服务：
+
+1. **连续多次收到错误邮件**
+2. **日志显示持续登录失败**
+3. **debug_page.html 显示异常内容**
+4. **失败率持续超过50%**
+
+其他情况下，让程序自动处理即可。
+
+## 对比：改进前 vs 改进后
+
+### 改进前
+```
+17:38:12 - ❌ 未找到成绩表格，解析到 0 门课程
+17:38:12 - 成绩无变化（共 0 门课程）  ← 直接当作正常
+17:38:12 - 等待 120 秒...              ← 不重试
+17:40:12 - 开始新一轮检查              ← 2分钟后才重试
+```
+
+### 改进后
+```
+17:38:12 - ❌ 未找到成绩表格
+17:38:12 - ⚠️ 解析到0门课程，但之前有8门课程
+17:38:12 - 等待 30 秒后重试...        ← 智能判断
+17:38:42 - ✅ 成功提取成绩信息         ← 快速恢复
+```
+
+---
+
+**总结：** 偶发性失败是网络应用的正常现象。新版本通过智能重试机制，将影响降到最低。只要失败率在合理范围（<20%），无需任何手动干预。
+
+**更新日期：** 2026-01-21  
+**版本：** v2.1 - 智能容错版