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

LeAudit Bridge 目录设计

1. 目标

fastapi_modules/fastapi_leaudit/leaudit_bridge/ 是 leaudit-platform 和 leaudit 内核之间的唯一正式桥接层。

设计目标：

• 业务层不直接调用 leaudit 内核模块
• 所有文档评查统一从 bridge 进入
• bridge 负责输入映射、上下文构建、结果适配、结果落库
• 后续替换或升级 leaudit 时，最大限度减少对业务层的影响

2. 目录结构

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. 数据流

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 ...	已移除（显式参数替代环境变量切换）