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

2026-04-28 11:44:31 +08:00
parent 1b4e0ec00a
commit be9fc4856b
15 changed files with 5733 additions and 0 deletions
@@ -0,0 +1,128 @@
+# LeAudit Bridge 目录设计
+
+## 1. 目标
+
+`fastapi_modules/fastapi_leaudit/leaudit_bridge/` 是 `leaudit-platform` 和 `leaudit` 内核之间的唯一正式桥接层。
+
+设计目标：
+
+- 业务层不直接调用 `leaudit` 内核模块
+- 所有文档评查统一从 bridge 进入
+- bridge 负责输入映射、上下文构建、结果适配、结果落库
+- 后续替换或升级 `leaudit` 时，最大限度减少对业务层的影响
+
+## 2. 目录结构
+
+```text
+fastapi_modules/fastapi_leaudit/leaudit_bridge/
+├── __init__.py              # 顶层入口：create_pipeline / is_leaudit_mode
+├── pipeline.py              # 管线总入口：OCR → Extract → Evaluate → Persist
+├── ctx_builder.py           # 构建 leaudit 执行上下文
+├── rules_loader.py          # 规则文件加载与缓存
+├── client_factory.py        # OCR/LLM/VLM 客户端工厂
+├── result_adapter.py        # leaudit 结果 → 统一格式
+├── storage_adapter.py       # 结果写入 leaudit_* 表（SQLAlchemy）
+├── tasks.py                 # Celery 异步任务入口
+├── ocr_bridge.py            # OCR/VLM 桥接后处理
+└── case_number_extractor.py # 案件编号提取
+```
+
+> 路径从老项目 `services/leaudit_bridge/` 变更为 `fastapi_modules/fastapi_leaudit/leaudit_bridge/`。
+
+## 3. 文件职责说明
+
+### `__init__.py`
+
+- `is_leaudit_mode()` — 新平台始终返回 True
+- `create_pipeline(rules_path)` — 创建完整 LauditPipeline 实例
+  - 使用 `DocNormalizationAdapter` 包裹 OCR 客户端
+  - 构建 `RulesFileRegistry` 用于内容分类
+
+### `pipeline.py`
+
+核心入口 `LauditPipeline.run()`：
+
+```
+document_id + file_path + rules_file
+  → OCR (含分类/分段/印章增强)
+  → 案件编号提取
+  → Extraction (dispatch_extract)
+  → 坐标解析 (resolve_bundle_positions)
+  → Phase 判定 (draft/executed)
+  → Evaluation (evaluate_extraction)
+  → StorageAdapter 落库
+```
+
+### `ctx_builder.py`
+
+把 leaudit-platform 文档对象映射成 leaudit 可执行上下文。
+
+### `rules_loader.py`
+
+- 本地 YAML 加载（`leaudit.dsl.loader.load_rules_file`）
+- 未来扩展：OSS 下载 + 缓存
+
+### `client_factory.py`
+
+统一创建 leaudit 运行所需依赖对象：
+
+- `create_ocr_client()` → `ChandraOCRClient`
+- `create_llm_client()` → `OpenAICompatibleClient`
+- `create_vlm_client()` → `QwenVLMClient`
+
+配置源：`fastapi_admin.config`（从 `app.toml` 加载）
+
+### `result_adapter.py`
+
+把 leaudit 的原始结果转换成统一消费结构，屏蔽内核对象细节变化。
+
+### `storage_adapter.py`
+
+将适配后的结果写入 `leaudit_*` 表：
+
+- `update_document_status()` → `leaudit_documents.processing_status`
+- `save_ocr_result()` → `leaudit_artifacts`
+- `save_extraction_result()` → `leaudit_field_results`
+- `save_evaluation_results()` → `leaudit_rule_results` + `leaudit_audit_runs`
+
+使用 SQLAlchemy `GetAsyncSession()` + `text()` 查询。
+
+### `tasks.py`
+
+Celery 异步任务入口。P2 阶段完成 Celery 集成。
+
+- `leaudit_process_document()` — 主处理函数
+- `dispatch_leaudit_task()` — 任务分发（P2 改用 `.apply_async()`）
+- `_resolve_rules_path()` — 规则路径解析（config → DB → type_id 映射）
+
+## 4. 调用边界约束
+
+- Controller 层不直接调用 `leaudit` 内核模块
+- Service 层不直接调用 `leaudit` 内核模块
+- 只有 `leaudit_bridge/` 可以感知 `leaudit` 内核类型和对象
+- 所有外部调用统一经过 `pipeline.py` 或 `tasks.py`
+
+## 5. 数据流
+
+```text
+Controller / Service
+  → leaudit_bridge.tasks.dispatch_leaudit_task
+  → leaudit_bridge.pipeline.LauditPipeline.run
+  → ctx_builder / rules_loader / client_factory
+  → leaudit 引擎执行
+  → result_adapter
+  → storage_adapter
+  → leaudit_* 结果表
+```
+
+## 6. 导入路径迁移
+
+从老项目迁移时，所有 `from core.*` 已更新为：
+
+| 旧引用 | 新引用 |
+|-------|-------|
+| `from core.config import ...` | `from fastapi_admin.config import ...` |
+| `from core.postgrest.client import ...` | SQLAlchemy `GetAsyncSession()` + `text()` |
+| `from core.logger import log` | `from fastapi_common.fastapi_common_logger import logger` |
+| `from core.celery_app_limited import celery_app` | P2 阶段集成 |
+| `from core.utils.instance_context import ...` | 已移除（显式参数替代环境变量切换） |