# 故障处理与降级

## 1. Python 依赖缺失

症状：`ModuleNotFoundError: playwright` 或 `No module named PIL`。

处理：

```bash
python -m pip install playwright pillow
python -m playwright install chromium
```

如果项目有自己的虚拟环境，优先在项目环境安装。无法安装时手工截图，并在报告中标记“未运行自动 DOM/SVG 检查”。

## 2. Chromium 无法启动

先运行 `python -m playwright install chromium`。无图形界面时保持 headless。仍失败则改用现有浏览器或把 PPTX/PDF 渲染成图片，但明确未验证真实交互全屏。

## 3. 页面无法被发现

默认选择器是 `.slide-card`。如果项目使用其他结构，传入：

```bash
python scripts/audit_courseware_visuals.py URL --slide-selector '.my-slide'
```

每个页面最好有稳定 ID 和连续页码属性。没有 ID 时脚本会临时生成，但源文件仍应补回稳定标识。

## 4. 全屏模式未识别

脚本原生识别 `openFullscreen(moduleId)` 和 `goToDeckPosition(moduleId, number)`。其他框架会退化为 2000×1200 大视口，并在报告中产生 `fullscreen-fallback`。

该降级不等于真实全屏验证。交付前应人工进入产品全屏并复核。

## 5. 自动报警过多

不要直接关闭报警。先按模式和类型聚合：

- 大量 `low-svg-font`：检查整页缩放、SVG viewBox 和响应式策略；
- 大量 `body-overflow`：检查全局行高、内边距或字体替换；
- 大量 `small-main-visual`：检查主图容器宽度和内容 `getBBox()`；
- 单页 `svg-text-clipped`：查看高清截图并修正标签位置或容器裁切。

阈值是报警线。对合理例外保留证据和说明，不偷偷忽略。

## 6. Manifest 校验失败

校验器会输出具体页码和字段。常见问题：

- `page` 重复或不是正整数；
- `level` 不是四个标准值；
- `hero`/`support` 缺少业务问题、类型或图注；
- `keep` 缺少保留原因；
- 类型名不是 kebab-case。

修正 JSON 后重跑，不在校验器中硬编码绕过。

## 7. PPTX 或 PDF 无法编辑

只有 PDF 或整页图片时：

1. 先保留原文件；
2. 提取文字与图形关系；
3. 在新的可编辑载体中重建；
4. 标记哪些元素是重建、哪些是原始证据；
5. 导出后逐页比对。

不要声称已经“修改源文件”。

## 8. 内容过密

修复顺序：删除重复表达 → 缩短标签 → 调整层级 → 扩大容器 → 拆页 → 最后小幅缩小字号。不要用全局缩小字号掩盖内容设计问题。

## 9. 业务关系不明确

列出无法确定的关系，例如“这是并列还是顺序”“未通过后是返工还是终止”“谁负责人工确认”。请求最小必要答案，在答案明确前不创建伪精确图形。

