# 间歇性解析失败说明

## 现象

日志显示偶尔出现解析失败，但下一次检查又恢复正常：

```
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 - 智能容错版