leaudit-platform-backend/docs/规则编辑/跑通全流程所需准备项.md

# LeAudit 跑通全流程所需准备项

## 1. 范围说明

本文记录的不是“仅把 YAML 规则搬到 OSS”这一件事，而是 **跑通 LeAudit 整个业务链路** 所需要补齐的能力。

这里的“跑通全流程”明确指：

```text
上传文档
  → 获取文件真源
  → OCR
  → 规则解析
  → 字段抽取
  → 评查
  →（可选）Rescue
  → 结果落库
  → 前端查询运行状态和结果
```

也就是说，目标不是只做“规则编辑”，而是要让下面这条链条在当前项目内真实可执行：

- 用户上传文档
- 平台找到该文档对应的规则版本
- Bridge 调用 `leaudit` 引擎执行 OCR / Extract / Evaluate
- 结果写入 `leaudit_*` 表
- 前端可以查询 run 状态和评查结果

---

## 2. 当前状态判断

当前项目的设计方向是对的，但距离“整条链真正可跑通”还有明显缺口。

> 2026-04-27 补充结论：结合 `/home/wren-dev/Porject/leaudit/src` 源码确认，`leaudit`
> 当前已经形成正式的服务编排层：`AuditCtx` +
> `AuditService.audit(ctx)`。因此本项目后续不应长期维持“平台自己手搓
> OCR / Extract / Evaluate / Rescue 编排”的模式，而应保留 bridge，
> 但把 bridge 改造成“平台对象 -> 原生 AuditCtx -> 原生 AuditService -> 平台持久化”的适配层。

### 2.1 已具备的基础

- 已有 `docs/leaudit/` 一整套设计文档
- 已有 `leaudit_*` 相关表设计与部分模型
- 已有 bridge 目录骨架：
  - `pipeline.py`
  - `tasks.py`
  - `rules_loader.py`
  - `storage_adapter.py`
- 已有规则集 / 规则版本 / 绑定表设计
- 已有 YAML 在线编辑设计文档：`docs/规则编辑/yaml规则在线编辑设计.md`

### 2.2 当前仍未闭环的关键问题

- 评查服务入口还没有真正触发可执行任务
- 规则加载仍以本地目录 / 硬编码过渡方案为主
- OSS 规则文件上传 / 下载 / 校验链未补齐
- 规则后台控制面未落地
- 运行结果与 `run_id` 的强绑定还不够严格
- 上传文件 → 文件真源 → 本地临时文件 → pipeline 的输入链还未完全收口

所以现在更准确的说法是：

- **架构蓝图已成型**
- **部分代码骨架已存在**
- **但全流程尚未真正打通**

---

## 3. 跑通整个流程，必须补齐的 8 大能力块

## 3.1 上传链路与文档真源

要跑通 OCR / 抽取 / 评查，首先必须保证上传文档在系统里成为一个稳定的“可执行输入”。

### 需要准备的能力

- 上传接口能够接收主文档 / 附件
- 上传后写入 `leaudit_documents`
- 文件元数据写入 `leaudit_document_files`
- 原始文件上传到 OSS 或稳定本地真源
- 为每个运行锁定 `document_file_id`
- 需要时可把文档从 OSS 下载到本地临时路径供 `leaudit` 读取

### 为什么这是前提

`leaudit` 执行时依赖本地文件路径，因此即便业务真源在 OSS，执行阶段仍要有：

```text
document_file.oss_url
  → 下载到本地临时文件
  → pipeline.run(file_path=local_tmp_path)
```

如果这一层不稳定，后面 OCR、抽取、评查都无从谈起。

---

## 3.2 评查运行主线（Run）管理

整条链必须围绕 `leaudit_audit_runs` 来组织，否则运行结果会失去可追踪性。

### 需要准备的能力

- 触发评查时先创建一条 `leaudit_audit_runs`
- 记录：
  - `document_id`
  - `document_file_id`
  - `run_no`
  - `trigger_source`
  - `status`
  - `rule_set_id`
  - `rule_version_id`
  - `rule_source_oss_url`
  - `rule_source_sha256`
- 运行中逐步更新：
  - `status`
  - `phase`
  - `started_at`
  - `finished_at`
  - 汇总统计字段

### 当前项目缺口

当前 `AuditServiceImpl.Run()` 还没有真正创建和分发 run，只是直接抛出“Celery 任务集成待实现”：

- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`

因此，当前“触发评查”这一步实际上还没有闭环。

---

## 3.3 规则管理控制面

如果未来要做 YAML 在线编辑，那么规则一定不能只是本地 `rules/` 目录，而必须成为平台管理对象。

### 需要准备的能力

- 规则集列表
- 规则版本列表
- 查看某个版本 YAML 内容
- 保存草稿版本
- 发布指定版本
- 回滚到历史版本
- 规则编辑 / 发布权限控制
- 发布 / 回滚审计

### 建议最少接口

- `GET /rule-sets`
- `GET /rule-sets/{rule_type}/versions`
- `GET /rule-versions/{id}/content`
- `POST /rule-sets/{rule_type}/versions`
- `POST /rule-sets/{rule_type}/validate`
- `POST /rule-sets/{rule_type}/publish`
- `POST /rule-sets/{rule_type}/rollback`

### 当前项目缺口

当前只有规则服务接口定义的一小部分骨架：

- `fastapi_modules/fastapi_leaudit/services/ruleService.py`

尚未形成完整规则后台能力。

---

## 3.4 规则文件存储链（OSS + DB）

这部分是“在线编辑”和“运行执行”之间的核心桥梁。

### 需要准备的能力

- YAML 文本上传到 OSS
- OSS 路径写入 `leaudit_rule_versions.oss_url`
- 同步保存：
  - `file_sha256`
  - `file_size`
  - `metadata_type_id`
  - `metadata_name`
  - `metadata_version`
- 下载规则文件到本地临时目录
- 下载后校验 sha256
- 发布后能根据 `current_version_id` 找到正在生效的版本

### 运行时目标链路

```text
leaudit_rule_type_bindings
  → leaudit_rule_sets.current_version_id
  → leaudit_rule_versions.oss_url
  → 下载到本地临时文件
  → load_rules_file(local_path)
  → 执行 pipeline
```

### 当前项目状态

当前项目已经开始按“原生 AuditCtx + Bridge 适配”方向落地两条来源链：

- 文档文件：
  - 已支持 `leaudit_document_files.local_path`
  - 也已支持 `leaudit_document_files.oss_url`
  - Worker 执行前会统一落为本地临时文件
- 规则文件：
  - 已支持 `leaudit_audit_runs.rule_source_oss_url`
  - 运行时按 `run -> rule_version -> oss_url` 下载 YAML 到本地临时文件
  - 再交给 `RulesLoader.load(local_path)` 与 `NativeRunner` 执行

当前仍保留 fallback：

- `LEAUDIT_RULES_DIR`
- `_TYPE_ID_RULES_MAP`
- 本地 `rules/` 目录

也就是说，“DB + OSS -> 本地临时 YAML”的正式主链已经接入，旧本地目录逻辑仅作为兼容回退。

---

## 3.5 规则校验链

规则编辑能力一旦开放，就必须要有保存前 / 发布前校验，否则很容易把错误 YAML 发到线上。

### 至少需要两层校验

#### 1）YAML 语法校验

- 缩进是否正确
- 结构是否可解析
- 基本字段是否存在

#### 2）LeAudit DSL 语义校验

- `metadata` 是否完整
- `type_id` / `version` / `name` 是否可识别
- rule / stage / extract 结构是否符合 `leaudit` 的 DSL 约束
- 规则中引用的字段是否存在
- phase / activate_if / score / risk 等配置是否合理

### 需要准备的结果形式

- 校验是否通过
- 错误列表
- 警告列表
- 可选：抽取出的 metadata 快照

---

## 3.6 执行链：OCR → 抽取 → 评查 → Rescue

这是整个系统真正的“核心业务流水线”。

### 需要准备的能力

- OCR 客户端可正常调用
- 文档分类 / rules resolve 可正常执行
- `dispatch_extract()` 能跑通字段抽取
- `evaluate_extraction()` 能完成规则评查
- 如果平台定义最终结果包含 Rescue，则补齐 rescue 阶段
- 执行链中每个阶段都要能记录错误与耗时

### 当前项目情况

`pipeline.py` 已有主链骨架：

- OCR
- 抽取
- 坐标解析
- phase detection
- evaluate

见：

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/pipeline.py`

但当前还存在这些问题：

- 结果存储依赖“按 document_id 查最新 run”这种简化逻辑
- rescue 尚未形成完整闭环
- 任务上下文仍残留 `source_port` 过渡参数
- 当前 `pipeline.py` 是平台侧自编排器，而不是调用 `leaudit` 原生
  `AuditService.audit(ctx)` 的适配包装器

因此还不能认为“执行链已经完全生产可用”。

### 最新架构修正建议

基于 `leaudit` 源码核对，正式建议改成：

```text
平台文档/规则/配置
  → bridge 解析输入
  → 构造 AuditServices
  → 构造 AuditConfig
  → 构造原生 AuditCtx
  → 调用 AuditService.audit(ctx)
  → 从最终 ctx 提取产物落库
```

也就是说：

- bridge 继续保留
- 但 bridge 不再负责自己重写 7 阶段编排
- bridge 负责“适配”和“持久化”
- `leaudit` 原生 `AuditService.audit(ctx)` 负责“执行”

---

## 3.7 结果落库与查询链

跑通全流程不只是引擎执行成功，还包括结果能写进去、查出来。

### 需要准备的能力

- OCR 产物写入 `leaudit_artifacts`
- 字段抽取结果写入 `leaudit_field_results`
- 规则评查结果写入 `leaudit_rule_results`
- 运行指标写入 `leaudit_run_metrics`
- 错误信息写入 `leaudit_run_errors`
- 补救结果写入 `leaudit_rescue_outcomes`
- 更新 `leaudit_audit_runs` 汇总字段
- 前端可查询：
  - run 状态
  - 规则级结果
  - 抽取字段
  - 汇总统计

### 当前项目缺口

当前 `StorageAdapter` 与 `AuditServiceImpl.GetResult()` 已明显向前推进，但还有工程缺口：

- 仍保留少量“按 document_id 找最新 run”的兼容路径
- 结果查询虽已能查规则/字段/errors/rescue/metrics/artifacts，但还缺前端最终展示口径梳理

见：

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`

这说明“结果查询主链已基本打通，但前端展示闭环仍待联调确认”。

---

## 3.8 异步任务、缓存、幂等与审计

如果只在本地同步跑 Demo，可以先简化；但如果要真的作为平台运行，就必须补齐基础工程能力。

### 需要准备的能力

#### 任务调度

- Celery / Redis 异步任务
- 任务超时
- 失败重试
- 队列优先级

#### 幂等与并发

- 同一个文档重复点击“评查”如何处理
- 同一 `run_id` 重试还是新建 run
- 避免结果串写到错误 run

#### 缓存失效

- 新规则发布后，旧缓存如何失效
- 多 worker 下规则缓存如何同步更新

#### 审计

- 谁上传了规则
- 谁发布了规则
- 谁触发了评查
- 该评查具体用了哪版规则

### 当前项目缺口

- Celery 仍未真正接入业务主链
- 发布后的规则缓存失效机制未明确实现
- 审计日志表和日志落库链未形成闭环

---

## 4. 从“规则编辑”到“全流程可跑”的完整依赖链

如果要把功能讲清楚，可以把整个系统拆成下面这条依赖链：

```text
【A】上传文档
  → 写 leaudit_documents / leaudit_document_files
  → 文件进 OSS

【B】编辑规则
  → YAML 文本保存
  → 语法/语义校验
  → 上传 rules.yaml 到 OSS
  → 写 leaudit_rule_versions
  → 发布切换 current_version_id

【C】触发评查
  → 创建 leaudit_audit_runs
  → 锁定 document_file_id + rule_version_id
  → 分发任务

【D】bridge 执行
  → 下载文档到本地临时文件
  → 下载规则到本地临时 YAML
  → OCR
  → Extract
  → Evaluate
  → Rescue（如启用）

【E】结果写回
  → artifacts / field_results / rule_results / metrics / errors
  → 更新 audit_runs 汇总

【F】前端查询
  → 查 run 状态
  → 查规则结果
  → 查字段结果
  → 展示最终评查报告
```

只有 A~F 都闭环，才能说“跑通整个流程”。

---

## 5. 建议的实施优先级

## P0：先跑通最小闭环

目标：先让“上传文档 -> 触发评查 -> OCR/抽取/评查 -> 结果查询”最小可用。

### P0 需要完成

- 上传文件能落真源
- `AuditServiceImpl.Run()` 真正可触发
- 创建 `leaudit_audit_runs`
- `pipeline.run()` 真正执行
- `StorageAdapter` 明确按 `run_id` 写结果
- `GetRunStatus()` / `GetResult()` 能查到真实数据

> 注意：这一阶段甚至可以暂时继续兼容本地 `rules/`，重点先是把业务主链打通。

---

## P1：切换规则真相源到 OSS + DB

目标：让规则不再依赖本地目录作为正式来源。

### P1 需要完成

- 规则版本上传到 OSS
- `leaudit_rule_versions` 完整入库
- `leaudit_rule_type_bindings` 真正生效
- `tasks.py` / `rules_loader.py` 走 `DB -> OSS -> 本地临时 YAML`
- `_TYPE_ID_RULES_MAP` 降级为 fallback

---

## P2：开放 YAML 在线编辑能力

目标：让规则成为后台可管理资产。

### P2 需要完成

- 规则列表 / 版本历史 / YAML 内容查看
- 编辑保存
- YAML 语法校验
- DSL 语义校验
- 发布 / 回滚
- 权限与审计

---

## P3：补齐平台级工程能力

目标：让系统从“能跑”升级到“稳定可运营”。

### P3 需要完成

- Celery 多队列
- Redis 缓存与缓存失效
- 幂等控制
- 失败重试
- 规则缓存刷新
- 跨区域权限 / 审计
- run_metrics / run_errors / rescue_outcomes 全量落库

---

## 6. 一句话结论

如果目标是“跑通整个流程：上传、OCR、抽取、评查”，那么除了“把规则 YAML 放 OSS、路径放数据库”之外，还必须同时补齐：

- 上传文件真源链
- 评查 run 主线
- 规则控制面
- 规则文件上传/下载/校验链
- 正式执行链
- 结果落库与结果查询链
- 任务、缓存、幂等、审计等基础设施能力

所以这不是一个单点功能，而是一条完整平台链路的闭环建设。

---

## 7. 当前项目的核心推进建议

按实际落地顺序，建议当前项目这样推进：

1. 先打通“上传 -> 触发评查 -> run -> 结果查询”最小链路
2. 再把规则解析从本地目录切到 `OSS + DB`
3. 然后再做 YAML 在线编辑、发布、回滚
4. 最后补缓存、审计、并发、重试等平台级能力

这样做的好处是：

- 可以尽快验证主业务链是否真实可用
- 不会在规则后台还没落地时就把复杂度全部堆上来
- 能明确区分“能跑通”和“能运营”的阶段目标