# devlog · PDF OCR 按需页面渲染回退（2026-07-29）

一句话：**修复 PDF 页面已因缺少机器可读文本而被质量路由选中，却因没有可直接消费的图像像素而无法 OCR 的问题；保留嵌入图像快路径，只对缺少像素输入的 OCR 路由页按需渲染最终页面外观。**

## 问题

质量路由能正确识别没有机器可读文本的页面，但 `PpOcrEnhancer` 原先只使用 IR 中已解码且像素长度合法的 `ImageChunk`。这一假设不只会漏掉仅暴露图像位置或无法直接解码图像流的 PDF，还会漏掉根本不存在整页图像对象的页面，例如由大量矢量路径绘制文字轮廓的页面。此类页面在阅读器中视觉非空，确定性解析却可能没有文本，OCR 也没有像素输入。

## 修复

- 新增 PDF 专用 OCR 输入适配器。逐页质量路由仍是第一道门：有机器可读文本的页面不调用模型，也不渲染；仅在被路由页没有可用嵌入像素时调用现有 `docparse-raster`。
- 临时注入整页 RGB `ImageChunk` 交给现有 PP-OCR 管线，增强完成后立即从 IR 删除临时图像。
- 嵌入 JPEG/RGB/Gray 像素仍走原快路径；否则由 PDF 渲染器执行完整页面绘制程序并生成最终 RGB 外观，因此不要求源页面必须包含图像对象。渲染失败时按原行为降级，不改确定性解析契约。
- CLI、批处理、REST 和 MCP 共用同一处 `EnhanceState`/`apply_ocr_with` 路径，无 IR、Schema 或对外 API 变更。

## 验收

- 合成单元测试覆盖临时页面渲染可被 OCR 消费且不泄漏到输出，以及仅有位置的图像不会被误当作可用输入。
- 本地非公开回归样本覆盖了“视觉页面主要由矢量路径组成、没有机器可读文本或整页图像对象”的情况；修复后文本大致可读，不再大面积输出空页或图像占位。
- 原本可提取机器文本的页面不进入 OCR；原本可解析样本的确定性输出逐字节不变。
- `cargo test --workspace`、`cargo fmt --all -- --check` 和锁文件约束下的 release 构建通过。

## 范围

本轮只解决“OCR 路由页缺少像素输入”这一明显功能缺口，不把页面渲染扩展到数字文本快路径，也不做版面高保真、OCR 精度调优或性能专项。
