degradation-strategy.md

按页降级策略

当 PDF 某页在 pipeline 中失败（如 OCR 超时、配色/裁剪异常）时，不中断整份任务，对该页采用降级占位，保证导出 PPTX 页数与原 PDF 一致，且用户可识别需手动调整的页面。

规则

1. 单页失败时

   • 该页使用原页图作为占位：将 PDF 该页渲染图整页插入为一张幻灯片，无文字块、无去字背景。
   • 用户可在 PowerPoint/WPS 中看到与原文一致的画面，并可自行裁剪或替换。

2. 整任务状态

   • 仅当全部页均失败时，将任务标记为 failed。
   • 只要存在至少一页成功或降级占位，任务标记为 completed，并生成 PPTX；failedPages 与 failureReasons 记录失败页索引及原因。

3. 导出元数据

   • GET /tasks/{taskId} 返回的 TaskStatus 包含：
     • failedPages：失败页的 0-based 索引列表；
     • failureReasons：可选，{ pageIndex: errorMessage }，供前端展示「第 X 页为降级」及原因。

前端展示

• 当 failedPages 非空时，在进度/导出完成区域展示提示，例如：「第 3、7 页为降级，建议在 PowerPoint 中检查并酌情调整。」
• 导出 PPTX 中，降级页为整页原图，与正常页（去字+文字+图片块）可区分。

与 Lite 模式的关系

• 当前降级占位采用「原页图」方案；后续若实现 Lite 模式（仅文字框、无样式），可扩展为「单页失败时使用 Lite 占位」的配置选项。