docs: add fix-double-finalize-and-bindings-api implementation plan

docs/leaudit/processing_logic.md

@@ -0,0 +1,153 @@
+# 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` 表