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

# LeAudit 文档域表结构设计

> **状态**: 已落地到 `leaudit_platform` 数据库（17 张表，全中文注释）  
> **设计基准**: `/home/wren-dev/Porject/leaudit/src/leaudit` 源码分析

## 1. 设计依据

本设计基于对 `leaudit` 源码的完整分析，对齐其真实的处理管线、数据模型和产出物类型。

### 1.1 LeAudit 处理管线（7 阶段）

```text
文件输入
  → Stage 1: Normalize（解析 → OCR → 分类 → 案卷分段 → 印章增强 → markdown 渲染）
  → Stage 2: Rules Resolve（加载 RulesFile）
  → Stage 3: Extract（字段抽取 → hydrate → multi-entity → derived → grounding）
  → Stage 4: Detect Phase（draft / executed 判定）
  → Stage 5: Evaluate（规则引擎 → 16 种 check 类型 → pass/fail/skip）
  → Stage 6: Rescue（失败规则补救：review → agent → pass/fail 翻转）
  → Stage 7: Finalize → Persist
```

### 1.2 LeAudit 自身存储模型（仅供参考，不做 leaudit-platform 真相源）

LeAudit 有一套自己的 SQLAlchemy ORM 表（`storage/models/`）。**leaudit-platform 不使用 LeAudit 的这套存储**。bridge 层（`storage_adapter.py`）已经绕过它，直接将结果写入 leaudit-platform 的 `leaudit_*` 表。

---

## 2. 设计原则

### 2.1 完全独立于业务表

所有 LeAudit 域表统一 `leaudit_*` 前缀，与老 `docauditai` 的 `documents` / `evaluation_points` 等表完全隔离。

### 2.2 数据库存索引，OSS 存真身

- OCR JSON、normalized JSON、markdown、页面图、裁切图 → OSS 文件
- 数据库只存元数据、状态、OSS 地址

### 2.3 一次执行一个 Run

每次文档进入 LeAudit 处理链，生成一条 `leaudit_audit_runs` 记录。支持重跑、版本回放、模型对比。

### 2.4 结果与产物解耦

- 结果表（rule_results / field_results）→ "这次跑出了什么"
- 产物表（artifacts）→ "这次跑的过程中生成了哪些文件"

---

## 3. 完整表清单

| # | 表名 | 用途 | 状态 |
|---|------|------|------|
| 1 | `leaudit_documents` | LeAudit 平台内部文档主表 | ✅ 已创建 |
| 2 | `leaudit_document_files` | 文档文件版本管理 | ✅ 已创建 |
| 3 | `leaudit_audit_runs` | 每次处理执行的主索引记录 | ✅ 已创建 |
| 4 | `leaudit_artifacts` | OCR/normalize/manifest/markdown/图片等文件产物索引 | ✅ 已创建 |
| 5 | `leaudit_rule_results` | 规则级评查结果（逐条规则一行） | ✅ 已创建 |
| 6 | `leaudit_field_results` | 字段级抽取结果 | ✅ 已创建 |
| 7 | `leaudit_run_metrics` | 各阶段耗时与计数统计 | ✅ 已创建 |
| 8 | `leaudit_run_errors` | 各阶段错误与诊断 | ✅ 已创建 |
| 9 | `leaudit_rescue_outcomes` | Rescue 补救结果 | ✅ 已创建 |
| 10 | `leaudit_rule_sets` | 规则集主表 | ✅ 已创建 |
| 11 | `leaudit_rule_versions` | 规则版本表 | ✅ 已创建 |
| 12 | `leaudit_rule_type_bindings` | 文档类型与规则集绑定 | ✅ 已创建 |
| 13 | `jwt_tokens` | JWT 令牌管理 | ✅ 已创建 |
| 14 | `leaudit_document_types` | 文档类型定义 | ✅ 已创建 |
| 15 | `leaudit_entry_modules` | 入口模块/导航菜单 | ✅ 已创建 |
| 16 | `leaudit_evaluation_point_groups` | 评查点规则组（PID 树形） | ✅ 已创建 |
| 17 | `leaudit_evaluation_points` | 规则点/评查点元数据 | ✅ 已创建 |

> 所有表均含 `create_time` / `update_time` / `delete_time` 三时间戳 + 中文列注释。  
> 详细建表 SQL 见 `scripts/schema_v2_add_evaluation_tables.sql`。

---

## 4. 核心表结构（文档执行域）

### 4.1 `leaudit_documents`

LeAudit 平台内部文档主表。当前不再依赖旧系统文档表。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | bigint PK | 主键，自增 |
| `biz_document_id` | bigint UNIQUE | 内部追踪号，沿用旧字段名以兼容历史库 |
| `type_id` | bigint | 文档类型 ID → `leaudit_document_types.id` |
| `processing_status` | varchar(64) | waiting / running / completed / failed |
| `current_run_id` | bigint | 最新有效 `leaudit_audit_runs.id` |
| `create_time` / `update_time` / `delete_time` | timestamptz | 标准时间戳 |

### 4.2 `leaudit_document_files`

文档文件表。一份文档可以有多个物理文件版本。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | bigint PK | 主键 |
| `document_id` | bigint FK | 关联 `leaudit_documents.id` |
| `file_role` | varchar(64) | primary / attachment / scan / ocr_result |
| `file_name` / `file_ext` / `mime_type` / `file_size` | — | 文件基本信息 |
| `sha256` | varchar(64) | 文件 SHA256 |
| `oss_url` | varchar(2048) | OSS 地址（真源） |
| `local_path` | varchar(1024) | 本地临时路径 |
| `is_active` | boolean | 当前生效文件 |
| `created_by` | bigint | 上传者 |

### 4.3 `leaudit_audit_runs`

核心追踪表。每次进入 LeAudit 主链生成一条记录。

| 字段分类 | 字段 | 说明 |
|---------|------|------|
| **标识** | `id` / `document_id` / `document_file_id` / `run_no` | 主键 + 关联 + 序号 |
| **触发** | `trigger_source` / `trigger_user_id` / `task_id` | 触发来源/人/Celery ID |
| **状态** | `status` / `phase` | pending→running→completed/failed |
| **规则溯源** | `rule_set_id` / `rule_version_id` / `rule_type_id` | 使用的规则版本 |
| | `rule_source_oss_url` / `rule_source_sha256` / `rule_local_cache_path` | 规则文件定位 |
| **模型快照** | `engine_version` / `llm_provider` / `llm_model` / `vlm_provider` / `vlm_model` / `ocr_provider` / `ocr_model` | 可追溯差异来源 |
| **Rescue** | `rescue_mode` / `rescue_applied` | 补救配置与执行标记 |
| **结果汇总** | `total_score` / `passed_count` / `failed_count` / `skipped_count` / `result_status` | 总量统计 |
| **时间** | `started_at` / `finished_at` / `create_time` / `update_time` | 时间追踪 |

### 4.4 `leaudit_artifacts`

统一产物表。记录一次 run 过程中产生的所有文件型中间产物。

**artifact_type 枚举（20 种）**：`original_doc` / `normalized_doc` / `render_png` / `render_pdf` / `ocr_json` / `extract_json` / `evaluate_json` / `rescue_json` / `quality_report` / `diff_report` / `cross_review` / `merged_result` / `final_report` / `vlm_render` / `vlm_vis_page` / `vlm_vis_subdoc` / `vlm_vis_field` / `vlm_debug` / `rescue_debug` / `pipeline_log`

### 4.5 `leaudit_rule_results`

规则级结果表。对齐 LeAudit `EvaluationResult.rules` 的实际字段。

| 字段分类 | 关键字段 | 说明 |
|---------|---------|------|
| **归属** | `run_id` / `rule_version_id` / `document_id` | 三重定位 |
| **规则标识** | `rule_id` / `rule_name` / `risk` / `score` | 规则基本信息 |
| **结果** | `passed` / `status` / `skip_reason` / `confidence` | 判定结果 |
| **消息** | `pass_message` / `fail_message` | 通过/失败文案 |
| **细节** | `stages` (jsonb) / `extracted_fields` (jsonb) / `field_positions` (jsonb) / `rule_meta` (jsonb) | 结构化详情 |
| **整改** | `remediation` (jsonb) / `rescue_applied` / `rescue_passed` | 补救信息 |
| **兜底** | `result_payload` (jsonb) | 完整 RuleResult JSON 备份 |

### 4.6-4.9 辅助表

- **`leaudit_field_results`**: 字段级抽取结果（value_text / confidence / grounding_score / hard_failed 等）
- **`leaudit_run_metrics`**: 各阶段耗时（ocr/normalize/extract/evaluate/rescue_seconds）+ 计数统计
- **`leaudit_run_errors`**: 各阶段错误（stage / level / error_code / message / detail_json）
- **`leaudit_rescue_outcomes`**: Rescue 补救结果（diagnosis / final_status / llm_calls / vlm_calls）

---

## 5. 规则管理域表

详见 [DSL 规则域表结构设计](dsl_rule_schema_design.md)。

| 表 | 用途 |
|----|------|
| `leaudit_rule_sets` | 规则集主表（rule_type / rule_name / current_version_id） |
| `leaudit_rule_versions` | 规则版本（oss_url / file_sha256 / metadata_* 快照） |
| `leaudit_rule_type_bindings` | 文档类型 ↔ 规则集绑定（binding_mode / priority） |

---

## 6. 评查点管理域表

| 表 | 用途 |
|----|------|
| `leaudit_evaluation_point_groups` | 评查点规则组（PID 树形层级） |
| `leaudit_evaluation_points` | 规则点/评查点（code / score / scoring_config / references_laws） |
| `leaudit_document_types` | 文档类型定义（code / classification_keywords / extraction_mode） |
| `leaudit_entry_modules` | 入口模块（name / path / areas / icon_path） |

---

## 7. 表关系图

```text
leaudit_entry_modules
  └── leaudit_document_types
        ├── leaudit_documents
        │     ├── leaudit_document_files
        │     └── leaudit_audit_runs
        │           ├── leaudit_artifacts (N)
        │           ├── leaudit_run_metrics (1)
        │           ├── leaudit_run_errors (N)
        │           ├── leaudit_rule_results (N)
        │           ├── leaudit_field_results (N)
        │           └── leaudit_rescue_outcomes (N)
        └── leaudit_rule_type_bindings
              └── leaudit_rule_sets
                    ├── leaudit_rule_versions
                    └── leaudit_evaluation_point_groups
                          └── leaudit_evaluation_points
```

---

## 8. OSS 路径约定

详见 [基础设施重设计](infrastructure_redesign.md) 第一节。

```text
# 业务文档
bdocs/{region}/{type_code}/{doc_id}/{version}/{file_role}.{ext}

# 评查产物
artifacts/{region}/{run_id}/{artifact_type}/{detail}.{ext}
```

---

## 9. 最终结论

- 所有表 `leaudit_*` 前缀，与老系统完全隔离
- `leaudit_documents` 现阶段是平台内部文档主表，不再要求外部 `documents.id`
- `leaudit_audit_runs` 是每次处理的唯一追踪单位
- `leaudit_artifacts` 统一管理所有文件产物，数据库只存索引
- `leaudit_rule_results` 粒度到逐条规则，结构与 LeAudit `RuleResult` 对齐
- 数据库已全部建表完成，含中文注释和三时间戳