# OCR与Workflow教训（2026-06-29 跃龙路校区）

## 1. 纯扫描件OCR：用ocrmypdf，不用raw tesseract

**问题**：跃龙路两份合同（租赁合同签字.pdf 11MB + 物业合同.pdf 1.4MB）都是纯扫描件（pdftotext提取0字符）。

**错误做法**：
- 用tesseract直接OCR → 输出大量乱码（"ARR: MEER"应该是"名称：范存益"，"FAK."应该是"平方米"）
- 试图用vision_analyze逐页核实 → 连续7次timeout，完全不可用
- 转而手动delegate_task让subagent做vision → 部分成功部分失败，耗费大量token和时间

**正确做法**：
```bash
# 首选：ocrmypdf（有预处理管线，中文识别质量远高于raw tesseract）
ocrmypdf -l chi_sim+eng --output-type pdf 原件.pdf OCR后.pdf
# 然后提取文字层
pdftotext OCR后.pdf output.md -layout
```

**ocrmypdf vs raw tesseract对比**：

| 维度 | ocrmypdf | raw tesseract |
|------|----------|---------------|
| 预处理 | 自动去噪、矫正、二值化 | 无 |
| 输出格式 | PDF+A（含文字层） | 纯文本 |
| 中文识别质量 | 较好（仍有少量错误） | 很差（大量乱码） |
| 适用场景 | 扫描件合同、手写签名页 | 印刷体清晰文档 |

**注意**：ocrmypdf输出仍有少量错误（空格分割、个别字误识），但整体可读性远优于raw tesseract。关键数字（金额、日期、面积）仍需人工或vision核实。

## 2. Vision工具timeout处理

**问题**：vision_analyze对大尺寸扫描件图片（>300KB）频繁timeout。压缩到100KB仍timeout。

**解决方案**：
1. 先尝试压缩：`PIL.Image.resize((1000, ...))` + JPEG quality=50
2. 如仍timeout，改用`browser_navigate(file://...)` + `browser_vision`
3. 如browser_vision也timeout，用`delegate_task`让subagent做（subagent有独立timeout预算）
4. 最终方案：用ocrmypdf替代vision做OCR，只在关键页面用vision核实

**最佳实践**：先用ocrmypdf做全量OCR，只对关键条款（租金金额、违约金比例、当事人名称）用vision逐页核实。不要试图vision每一页。

## 3. uwf workflow必须使用

**教训**：Maggie明确指出"跃龙路又没有按照workflow进行了"。手动做OCR+分析+建表=跳步+质量失控。

**正确流程**：
1. 用ocrmypdf做OCR（或用已有校正OCR文本）
2. 启动uwf `nantong-lease-audit` workflow（4角色：classifier→template-diff→rule-analyzer→data-extractor）
3. 每个合同一个thread，可并行启动
4. 等待所有thread完成（约10-15分钟/合同）
5. 读取JSON输出喂给`single-campus-builder.py`

**uwf启动命令**：
```bash
# 启动thread
uwf thread start nantong-lease-audit -p "校区：X | 合同文件：Y.pdf | OCR文本路径：/tmp/xxx/Y_ocr.md | 原始文件名：Y.pdf"
# 后台执行（最多10步）
uwf thread exec <thread-id> --count 10 --background
# 检查进度
uwf thread show <thread-id>
# 读取结果
uwf thread read <thread-id> --quota 8000
```

**JSON输出路径**：`/tmp/nantong-lease-audit/<校区>-row-data.json`

## 4. delivery-gate.py文件名模式

**G1检查**：寻找`模版比对-*.md`格式的文件名（不是`*-template-diff.md`）。
- ✅ 正确：`模版比对-跃龙路租赁合同.md`
- ❌ 错误：`跃龙路-template-diff.md`

**修复**：workflow产出的template-diff文件需要复制或重命名：
```bash
cp /tmp/nantong-lease-audit/跃龙路-template-diff.md /tmp/<校区>/模版比对-跃龙路租赁合同.md
```

**G5检查**：`数据行数≥3`是默认值。对于只有2份合同的校区（租赁+物业），这是**正常情况**，不算失败。如果G5报错但确认校区确实只有2份合同，可安全忽略此项。

## 5. 物业合同JSON被覆盖

**问题**：两个合同共用同一个uwf workflow名称（`nantong-lease-audit`），data-extractor角色默认写入`/tmp/nantong-lease-audit/row_data.json`。如果两个thread同时跑，后完成的会覆盖先完成的。

**解决方案**：
- 物业合同没有对应的07模版，不需要走template-diff角色
- 物业合同的K列和L列内容需要手动填充（从OCR文本+workflow摘要中提取）
- 或者：在builder脚本中直接从OCR文本和物业合同分析摘要手动构造物业数据行

## 6. ocrmypdf产出仍需OCR完整性检查

ocrmypdf产出文字层后，用pdftotext提取的.md文件可能仍有少量乱码。需要：
1. 运行`ocr-integrity-check.py`检查乱码
2. 如果检查失败（检测到公司名乱码等），用vision核实关键页
3. 核实后手动修正.md文件中的乱码
4. 重新运行检查直到通过，生成`step1.verified` checkpoint

**快捷方案**：如果之前已有vision校正过的.md文件（本次session中手动校正的），直接复用，不需要重新跑ocrmypdf+检查流程。