# LeAudit Platform — 系统现状总览

> 最后更新：2026-04-28

## 一、目标架构

```
┌─ API ───────────────────────────────────────────────────────────┐
│  AuditController (/audit)          RuleController (/rule-sets)   │
│  POST /run      触发评查           GET  /              规则集列表 │
│  GET  /run/:id  查询状态           GET  /{type}/versions 版本列表 │
│  GET  /result/:id 查询结果         GET  /versions/:id/content 正文│
│                                    POST /{type}/validate  校验   │
│                                    POST /{type}/versions  创建   │
│                                    POST /{type}/publish   发布   │
│                                    POST /{type}/rollback  回滚   │
│                                    GET  /bindings        绑定列表 │
│                                    POST /{type}/bindings 创建绑定│
│                                    PUT  /bindings/{id}   更新绑定│
│                                    DELETE /bindings/{id} 删除绑定│
├─ Service ───────────────────────────────────────────────────────┤
│  AuditServiceImpl                RuleServiceImpl + OssServiceImpl│
├─ Bridge ────────────────────────────────────────────────────────┤
│  FileSourceResolver  RuleVersionResolver  RulesLoader            │
│  AuditCtxBuilder     AuditServiceFactory  NativeRunner           │
│  StorageAdapter      ResultAdapter        RuleValidator          │
│  tasks.py (dispatch_leaudit_task)                                │
├─ leaudit (不改) ────────────────────────────────────────────────│
│  AuditCtx → AuditService.audit() → OCR/Normalize/Extract/       │
│  Evaluate/Rescue → 填充 ctx.normalized_doc/extraction/           │
│  evaluation/fallback_tasks/timing/extraction_errors              │
├─ 存储 ──────────────────────────────────────────────────────────┤
│  OSS (MinIO)                        PostgreSQL                  │
│  bdocs/{region}/{type}/{doc_id}/    leaudit_documents           │
│  rules/{rule_type}/{version_no}/    leaudit_document_files      │
│  artifacts/{region}/{run_id}/       leaudit_audit_runs          │
│                                     leaudit_rule_sets           │
│                                     leaudit_rule_versions       │
│                                     leaudit_rule_type_bindings  │
│                                     leaudit_rule_results        │
│                                     leaudit_field_results       │
│                                     leaudit_run_metrics         │
│                                     leaudit_run_errors          │
│                                     leaudit_rescue_outcomes     │
│                                     leaudit_artifacts           │
└─────────────────────────────────────────────────────────────────┘
```

## 二、两条核心数据流

### 流 A：规则生命周期

```
编辑 YAML
  → POST /rule-sets/{type}/validate → RuleValidator (YAML语法 + DSL语义)
  → POST /rule-sets/{type}/versions → 上传 OSS + INSERT leaudit_rule_versions
  → POST /rule-sets/{type}/publish  → UPDATE leaudit_rule_sets.current_version_id
  → POST /rule-sets/{type}/bindings → INSERT leaudit_rule_type_bindings
  → 新 run 自动绑定新版本到对应文档类型
```

### 流 B：评查执行

```
POST /audit/run { documentId }
  → AuditServiceImpl.Run()
    1. 查 leaudit_documents + leaudit_document_files
    2. 查 leaudit_rule_type_bindings → rule_set_id + rule_version_id
    3. INSERT leaudit_audit_runs (rule_version_id, rule_source_oss_url, sha256)
    4. FileSourceResolver → 下载文档 bytes
    5. dispatch_leaudit_task()
       ┌─ RuleVersionResolver → OSS 下载规则 YAML → SHA256 校验
       ├─ RulesLoader → RulesFile
       ├─ NativeRunner.run() → AuditCtx → AuditService.audit()
       └─ NativeRunner.persist_result()
          ├─ save_ocr_result()         → leaudit_artifacts
          ├─ save_extraction_result()  → leaudit_field_results
          ├─ save_evaluation_results() → leaudit_rule_results + 分数
          ├─ save_run_errors()         → leaudit_run_errors
          ├─ save_rescue_outcomes()    → leaudit_rescue_outcomes
          ├─ save_run_metrics()        → leaudit_run_metrics
          └─ finalize_run()            → 终态 (result_status/finished_at)
```

## 三、模块完成度

### M1：OSS 基础设施 — 100%

| 文件 | 状态 | 说明 |
|---|---|---|
| `fastapi_common/fastapi_common_storage/oss_client.py` | 已完成 | 上传/下载/Presign/ObjectExists |
| `fastapi_common/fastapi_common_storage/oss_path_utils.py` | 已完成 | BuildBusinessDocKey/ArtifactKey/RuleYamlKey |
| `fastapi_admin/config/_settings.py` | 已完成 | OSS_ENDPOINT/ACCESS_KEY/SECRET_KEY/BUCKET/REGION/USE_SSL/PRESIGN_EXPIRE |
| `fastapi_admin/config/__init__.pyi` | 已完成 | 类型声明 |

### M2：规则管理后端 — 100%

| 文件 | 状态 | 说明 |
|---|---|---|
| `controllers/ruleController.py` | 已完成 | 11 个端点（含绑定管理） |
| `services/ruleService.py` | 已完成 | IRuleService 接口 |
| `services/impl/ruleServiceImpl.py` | 已完成 | 规则 CRUD + 绑定 CRUD |
| `leaudit_bridge/ruleValidator.py` | 已完成 | YAML 语法 + DSL 语义校验 |
| `domian/Dto/ruleVersionCreateDto.py` | 已完成 | 创建版本 DTO |
| `domian/Dto/ruleValidateDto.py` | 已完成 | 校验 DTO |
| `domian/Dto/rulePublishDto.py` | 已完成 | 发布/回滚 DTO |
| `domian/Dto/ruleBindingDto.py` | 已完成 | 绑定 DTO |
| `domian/vo/ruleVo.py` | 已完成 | RuleSetVO/VersionVO/ContentVO/ValidationVO/BindingVO |

### M3：执行链与持久化 — ~95%

| 文件 | 状态 | 说明 |
|---|---|---|
| `leaudit_bridge/auditCtxBuilder.py` | 已完成 | 构建原生 AuditCtx |
| `leaudit_bridge/auditServiceFactory.py` | 已完成 | 创建 AuditService |
| `leaudit_bridge/nativeRunner.py` | 已完成 | 原生执行入口 + persist_result |
| `leaudit_bridge/fileSourceResolver.py` | 已完成 | 文档来源解析（接 OSS） |
| `leaudit_bridge/ruleVersionResolver.py` | 已完成 | 规则版本解析（含 SHA256） |
| `leaudit_bridge/storage_adapter.py` | 已完成 | 全部持久化方法（已修双重 finalize） |
| `leaudit_bridge/tasks.py` | 已完成 | 任务入口 + 失败处理 |
| `leaudit_bridge/pipeline.py` | 待退役 | 旧管线（已被 nativeRunner 替代） |
| `leaudit_bridge/client_factory.py` | 90% | OCR/LLM/VLM 客户端工厂 |

### M4：全流程联调 — 0%

| 项目 | 状态 |
|---|---|
| 上传入口梳理 | 待做 |
| 上传后自动触发评查 | 待做 |
| 结果查询展示 | 待做 |
| 联调样例准备 | 待做 |
| E2E 验证 | 待做 |

## 四、持久化执行顺序与终态

`persist_result()` 严格按以下顺序执行，`finalize_run` 在最后是唯一的终态写入者：

```
save_ocr_result()
save_extraction_result()
save_evaluation_results()    ← 只写分数/计数，不写 finished_at
save_run_errors()
save_rescue_outcomes()
save_run_metrics()
finalize_run()               ← 唯一写 result_status / finished_at / rescue_applied / phase
```

**终态来源（直接从 AuditCtx 读取，不另存平行状态）：**

| 平台表 | 来源 |
|---|---|
| `leaudit_run_metrics` | `ctx.timing` |
| `leaudit_run_errors` | `ctx.extraction_errors` + `ctx.extraction.all_errors` |
| `leaudit_rescue_outcomes` | `ctx.fallback_tasks` |
| `leaudit_audit_runs.result_status` | 综合 `ctx.fallback_tasks` + `ctx.evaluation` 推导 |
| `leaudit_audit_runs.finished_at` | `finalize_run` 写入 now() |
| `leaudit_audit_runs.rescue_applied` | `bool(ctx.fallback_tasks)` |

## 五、数据库表关系

```
leaudit_document_types
  └── leaudit_rule_type_bindings (doc_type_id → rule_set_id)
        └── leaudit_rule_sets (current_version_id)
              └── leaudit_rule_versions (oss_url, sha256)
                    └── leaudit_audit_runs (rule_version_id, rule_source_oss_url)
                          ├── leaudit_rule_results
                          ├── leaudit_field_results
                          ├── leaudit_run_metrics
                          ├── leaudit_run_errors
                          ├── leaudit_rescue_outcomes
                          └── leaudit_artifacts
```

## 六、关键设计原则

1. **leaudit 核心不改** — 所有定制在 bridge 层，leaudit 保持纯 Python 包
2. **只读 AuditCtx** — 执行完只从 ctx 上读取，不自己模拟 stage
3. **规则版本溯源** — 每个 run 绑定具体 `rule_version_id`，老 run 不受新发布影响
4. **OSS 真源 + DB 索引** — YAML 正文存 OSS，元数据索引存 PostgreSQL
5. **终态单点写入** — `finalize_run` 是 run 主表终态的唯一写入者
6. **独立 session 提交** — 每个 `save_*` 独立会话，按"先子表后主表"顺序保证最终一致性

## 七、已知待补项

| 缺口 | 优先级 |
|---|---|
| `run_metrics.llm_call_count` / `vlm_call_count` 仍为空 | P1（可从 RescueTask 汇总） |
| `ctx.timing` 缺 normalize/rescue 独立 key | P2（等 leaudit 原生补） |
| 文档状态更新逻辑分散在两处 | P1（应收敛到 StorageAdapter） |
| Celery 异步化 | P2（当前同步可跑通，生产需异步） |
| `_TYPE_ID_RULES_MAP` 硬编码兜底 | P2（等 bindings 全覆盖后移除） |
| M4 E2E 联调 | P0（下个里程碑） |