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