# LeAudit 处理逻辑说明

> 描述 leaudit 引擎的完整流水线阶段，新老项目通用。

## 1. 主链概览

`leaudit` 的完整处理链不是单一 OCR 流程，而是一条完整评查流水线：

```text
文件输入
  → normalize
  → rules resolve
  → extract
  → determine phase
  → evaluate
  → rescue
  → persist / adapt result
```

## 2. 各阶段说明

### 2.1 normalize

职责：

- 文档解析
- OCR 或文本提取
- 文档分类
- 案卷分段
- 印章/签名增强
- 统一形成归一化结果对象

产出：

- `normalized_doc`
- 原始文本
- 分类结果
- 视觉清单（VisualManifest）
- 子文档结构

### 2.2 rules resolve

职责：

- 按输入文档类型或分类结果找到 DSL 规则文件
- 解析成 `RulesFile`

leaudit-platform 做法：

- 由 bridge 层显式完成规则映射（`rules_loader.py`）
- 规则从 OSS 下载到本地临时文件后加载
- 支持 `leaudit_rule_type_bindings` 表查绑定 → `leaudit_rule_versions.oss_url` 下载

### 2.3 extract

职责：

- 按 schema 分组抽取字段
- 进行 null-field retry / deep retry
- hydrate 类型化
- multi-entity 展开
- derived 字段计算
- post-hoc grounding
- seal/signature 补充抽取

产出：

- 结构化字段
- 多实体字段
- derived 字段
- 抽取错误列表

### 2.4 determine phase

职责：

- 识别文档属于 `draft` 还是 `executed`
- 决定后续哪些规则参与执行

注意：

- `leaudit` 的策略是先用 `executed` 全量抽取，再反向判定 phase
- 接入时不要外层再强行重复做另一套 phase 判定逻辑

### 2.5 evaluate

职责：

- 执行 DSL rules
- 经过 phase filter、activate_if、confidence gate
- 逐条 rule 输出 pass/fail/skip
- 计算分数、失败原因、整改建议

产出：

- 文档级评查结果
- 规则级结果列表

### 2.6 rescue

职责：

- 对失败规则做补救判定
- 可能把失败翻转为通过

注意：

- rescue 后的最终聚合结果才是业务最终结果
- 落库时要认最终结果，不要混用 pre-rescue 和 post-rescue 状态

## 3. Bridge 层的输入要求

bridge 层（`fastapi_modules/fastapi_leaudit/leaudit_bridge/`）至少要准备：

- `document_id`
- 可读的本地文件路径
- 对应 `RulesFile`
- OCR/LLM/VLM 客户端
- 结果落库适配器（`storage_adapter.py`）

## 4. Bridge 层的输出

统一整理出：

- 文档级总结果：`total_score` / `passed_count` / `failed_count` / `skipped_count` / `timing`
- 规则级结果：`rule_id` / `rule_name` / `passed` / `status` / `score` / `risk` / `message` / `remediation`
- 抽取结果：`extraction_fields` / `derived_fields` / `multi_entity`

## 5. 对接时的关键约束

### 文件路径

`leaudit` 许多逻辑默认依赖本地文件路径，因此 bridge 层必须保证：

- 文档能以本地文件形式供其读取
- 如果文件在对象存储中，需先下载到临时路径

### 配置统一

不要让 `leaudit` 在项目里形成另一套独立配置真相源。

由项目统一注入：

- OCR 配置（`app.toml` → `fastapi_admin.config.OCR_*`）
- LLM 配置（`app.toml` → `fastapi_admin.config.LLM_*`）
- VLM 配置（`app.toml` → `fastapi_admin.config.VLM_*`）
- 并发控制配置

### 存储隔离

- `leaudit` 内部计算
- bridge 适配后写入 `leaudit_*` 统一结果表
- 不使用 leaudit 自己的默认 `documents/extractions/evaluations` 表