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 阶段）

文件输入
  → 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 规则域表结构设计。

表	用途
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. 表关系图

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 路径约定

详见 基础设施重设计 第一节。

# 业务文档
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 对齐
• 数据库已全部建表完成，含中文注释和三时间戳