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

2026-04-28 11:44:31 +08:00
parent 1b4e0ec00a
commit be9fc4856b
15 changed files with 5733 additions and 0 deletions
@@ -0,0 +1,520 @@
+# 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` 已有部分写入逻辑，但还有明显工程缺口：
+
+- 多处依赖“按 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. 从“规则编辑”到“全流程可跑”的完整依赖链
+
+如果要把功能讲清楚，可以把整个系统拆成下面这条依赖链：
+
+```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. 最后补缓存、审计、并发、重试等平台级能力
+
+这样做的好处是：
+
+- 可以尽快验证主业务链是否真实可用
+- 不会在规则后台还没落地时就把复杂度全部堆上来
+- 能明确区分“能跑通”和“能运营”的阶段目标