leaudit-platform-backend/docs/leaudit/processing_logic.md

LeAudit 处理逻辑说明

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

1. 主链概览

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

文件输入
  → 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 表