# OCR 票据识别架构

## 1. 定位

OCR 票据识别不是一个简单的图片转文字功能。

它在 X-Financial 中承担三件事：

1. 把用户上传的附件变成结构化票据信息。
2. 为规则中心提供可判断的字段。
3. 为 Hermes 和 User Agent 提供可解释的证据。

因此 OCR 应作为独立能力纳入 Capability Registry。

```text
capability_type = mcp | document_processor
capability_code = invoice_ocr
```

## 2. 总体链路

```text
附件上传
  ↓
文件分类
  ↓
OCR 识别
  ↓
字段结构化
  ↓
票据类型归一化
  ↓
发票验真 MCP
  ↓
与报销明细匹配
  ↓
规则中心检查
  ↓
人工修正
  ↓
修正结果沉淀
```

## 3. 阶段拆分

### Phase A：附件接入与文件分类

目标：先识别上传的是什么。

输入：

- 图片。
- PDF。
- Excel。
- Word。
- 压缩包。

输出：

```json
{
  "document_type": "invoice",
  "mime_type": "image/png",
  "page_count": 1,
  "confidence": 0.91
}
```

分类结果：

```text
invoice
itinerary
contract
payment_receipt
approval_screenshot
other
```

### Phase B：OCR 字段提取

目标：从图片或 PDF 中提取票据字段。

结构：

```json
{
  "invoice_code": "",
  "invoice_number": "",
  "seller_name": "",
  "seller_tax_no": "",
  "buyer_name": "",
  "buyer_tax_no": "",
  "issue_date": "",
  "total_amount": 0,
  "tax_amount": 0,
  "currency": "CNY",
  "ocr_confidence": 0.88
}
```

### Phase C：字段归一化

目标：不同 OCR 服务返回不同字段名，必须统一。

示例：

```text
发票号码 / invoiceNo / invoice_number
  -> invoice_number
```

金额统一：

```json
{
  "raw": "￥1,280.00",
  "value": 1280.00,
  "currency": "CNY"
}
```

### Phase D：验真与状态检查

调用发票验真 MCP。

输出：

```json
{
  "verify_status": "verified",
  "voided": false,
  "red_reversed": false,
  "verified_at": ""
}
```

### Phase E：与报销明细匹配

对比：

- 发票金额 vs 报销金额。
- 开票日期 vs 费用日期。
- 销售方 vs 商户。
- 发票类型 vs 费用类型。

输出：

```json
{
  "match_status": "matched",
  "mismatch_fields": [],
  "match_confidence": 0.94
}
```

### Phase F：人工修正与回流

OCR 结果必须允许人工修正。

修正内容进入反馈池：

```json
{
  "field": "invoice_number",
  "before": "12345B",
  "after": "123456",
  "corrected_by": "finance_user",
  "corrected_at": ""
}
```

## 4. 数据模型建议

```text
document_assets
document_ocr_results
invoice_structured_records
invoice_verification_records
document_corrections
```

## 5. 与规则中心关系

OCR 输出供规则使用：

```text
重复报销识别规则
作废发票检查规则
发票抬头异常规则
附件完整性规则
金额不一致规则
```

## 6. 与 Agent 关系

User Agent 使用 OCR：

- 解释发票为什么被拦截。
- 帮用户补充发票信息。
- 提醒上传清晰附件。

Hermes 使用 OCR：

- 夜间批量验真。
- 扫描重复票据。
- 统计发票异常趋势。

## 7. 开发阶段建议

```text
Step 1: 附件上传和文件分类
Step 2: 接入 OCR MCP
Step 3: 结构化字段归一化
Step 4: 人工修正界面
Step 5: 发票验真 MCP
Step 6: 与报销明细匹配
Step 7: 规则中心接入
Step 8: Hermes 夜间批量 OCR 巡检
```