TanWenyan/leaudit-platform-backend

Fork 0

Files

T

wren be9fc4856b docs: add fix-double-finalize-and-bindings-api implementation plan

2026-04-28 11:44:31 +08:00

14 KiB

Raw Blame History

LeAudit 跑通全流程所需准备项

1. 范围说明

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

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

上传文档
  → 获取文件真源
  → 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，执行阶段仍要有：

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 找到正在生效的版本

运行时目标链路

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) 的适配包装器

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

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 已有部分写入逻辑，但还有明显工程缺口：

多处依赖“按 document_id 找最新 run”
GetResult() 仍未从 leaudit_rule_results 真正查规则级结果

见：

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. 从“规则编辑”到“全流程可跑”的完整依赖链

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

【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. 当前项目的核心推进建议

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

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

这样做的好处是：

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

14 KiB Raw Blame History Unescape Escape

LeAudit 跑通全流程所需准备项

1. 范围说明

2. 当前状态判断

2.1 已具备的基础

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

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

3.1 上传链路与文档真源

需要准备的能力

为什么这是前提

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

需要准备的能力

当前项目缺口

3.3 规则管理控制面

需要准备的能力

建议最少接口

当前项目缺口

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

需要准备的能力

运行时目标链路

当前项目状态

3.5 规则校验链

至少需要两层校验

1）YAML 语法校验

2）LeAudit DSL 语义校验

需要准备的结果形式

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

需要准备的能力

当前项目情况

最新架构修正建议

3.7 结果落库与查询链

需要准备的能力

当前项目缺口

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

需要准备的能力

任务调度

幂等与并发

缓存失效

审计

当前项目缺口

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

5. 建议的实施优先级

P0：先跑通最小闭环

P0 需要完成

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

P1 需要完成

P2：开放 YAML 在线编辑能力

P2 需要完成

P3：补齐平台级工程能力

P3 需要完成

6. 一句话结论

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

14 KiB

Raw Blame History