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,721 @@
+## 背景
+
+当前 `leaudit-platform` 已经完成第一阶段原生执行链接入：
+
+- 文档文件已开始支持 `ossUrl -> 本地临时文件 -> NativeRunner`
+- 规则文件已开始支持 `run -> rule_source_oss_url -> 本地临时 YAML -> NativeRunner`
+- 执行核心已经切到原生 `AuditCtx` / `AuditService`
+- `leaudit` 核心不修改，平台继续通过 bridge 适配
+
+但当前仍有三个关键缺口没有真正完成闭环：
+
+1. 还没有统一 OSS 服务，文档/规则下载仍是临时实现
+2. 还没有完整的规则 YAML 管理后端能力
+3. 还没有把“上传 → OCR → 抽取 → 评查 → 查询结果”整条链路正式联调跑通
+
+因此需要制定一份统一实施计划，按依赖顺序把这三块一起完成。
+
+---
+
+## 总目标
+
+本轮实施的目标分为三部分：
+
+### 目标 1：统一 OSS 服务
+
+把当前 bridge 中分散的下载逻辑收敛成统一的 OSS / MinIO 能力层，供文档文件、规则 YAML、运行产物三类对象复用。
+
+### 目标 2：补齐规则管理后端
+
+支持规则 YAML 的：
+
+- 内容校验
+- 新版本上传
+- 版本持久化
+- 当前版本发布
+- 历史版本回滚
+- 版本正文读取
+
+并为后续在线编辑界面提供稳定后端。
+
+### 目标 3：打通完整评查流程
+
+跑通最小完整业务闭环：
+
+```text
+上传文档
+  -> 文档入库
+  -> 文件入 OSS / 或存在可访问真源
+  -> 创建 run
+  -> 下载文档到本地临时文件
+  -> 下载规则 YAML 到本地临时文件
+  -> Native AuditCtx 执行
+  -> OCR / 抽取 / 评查
+  -> 结果写回 leaudit_*
+  -> 查询运行状态和结果
+```
+
+---
+
+## 当前已完成基线
+
+### 已完成
+
+- `AuditServiceImpl.Run()` 已可创建 `leaudit_audit_runs` 并触发执行
+- `AuditServiceImpl.GetResult()` 已可读取 `leaudit_rule_results`
+- 文档文件执行链已接入：
+  - `LeauditDocumentFile.localPath`
+  - `LeauditDocumentFile.ossUrl`
+- 规则文件执行链已接入：
+  - `LeauditAuditRun.ruleVersionId`
+  - `LeauditAuditRun.ruleSourceOssUrl`
+  - `run -> oss_url -> 本地临时 YAML -> RulesLoader -> NativeRunner`
+- bridge 层已经新增：
+  - `auditCtxBuilder.py`
+  - `auditServiceFactory.py`
+  - `nativeRunner.py`
+  - `fileSourceResolver.py`
+  - `ruleVersionResolver.py`
+
+### 尚未完成
+
+- 统一 OSS client / path utils 还未落地
+- 规则上传 / 发布 / 回滚 / 读正文接口还未落地
+- YAML 语法校验和 DSL 语义校验还未形成正式服务
+- `run_metrics` / `run_errors` / `rescue_outcomes` 持久化还未补齐
+- 全流程 E2E 还未完成真实联调
+
+### 当前实施进展（2026-04-27）
+
+- `M1` 已开始落地：
+  - 已补 `OSS_USE_SSL` / `OSS_PRESIGN_EXPIRE_SECONDS` 等配置项
+  - 已新增统一 `OssClient` 与 `OssPathUtils`
+  - `fileSourceResolver.py` / `ruleVersionResolver.py` 已开始接统一 OSS 服务
+- `M2` 已开始落地：
+  - 已新增 `ruleValidator.py`
+  - 已补 `ruleServiceImpl.py`
+  - 已新增 `ruleController.py`
+  - 已补规则版本创建 / 校验 / 发布 / 回滚 / 正文读取接口骨架
+- `M3` 已开始落地：
+  - 已按 `docs/AuditCtx深度解读-2026-04-27.html` 复用原生 `AuditCtx` 语义
+  - 已开始把 `ctx.timing` / `ctx.fallback_tasks` / 抽取错误落库到运行级表
+- `M4` 仍待继续实施
+
+---
+
+## 总体实施分期
+
+建议分 4 个里程碑实施：
+
+- `M1`：统一 OSS 基础设施
+- `M2`：规则管理后端能力
+- `M3`：执行链正式化与结果持久化补齐
+- `M4`：全流程联调与验收
+
+实施顺序必须按依赖推进，不建议跳步。
+
+---
+
+## M1：统一 OSS 基础设施
+
+### M1-1 配置模型标准化
+
+#### 目标
+
+统一 OSS / MinIO 的配置读取方式，为后续文档和规则服务提供底层能力。
+
+#### 需要处理
+
+- 新增或确认 OSS 配置项
+- 保证配置能从 `app.toml` / 环境变量进入 Settings
+- 补齐 `__init__.pyi` 类型声明
+
+#### 建议配置项
+
+- `OSS_ENDPOINT`
+- `OSS_BUCKET`
+- `OSS_ACCESS_KEY`
+- `OSS_SECRET_KEY`
+- `OSS_REGION`
+- `OSS_USE_SSL`
+- `OSS_PUBLIC_BASE_URL`
+- `OSS_PRESIGN_EXPIRE_SECONDS`
+
+#### 需要修改的文件
+
+- `fastapi_admin/config/_settings.py`
+- `fastapi_admin/config/__init__.pyi`
+- 环境配置文件（如有）
+
+#### 完成标准
+
+- 业务代码可以统一 import OSS 配置
+- IDE 类型可识别
+- 开发 / 测试 / 生产环境可分离
+
+### M1-2 统一 OSS Client
+
+#### 目标
+
+提供平台统一的上传、下载、presign 和对象存在性判断能力。
+
+#### 建议新增文件
+
+- `fastapi_common/fastapi_common_storage/oss_client.py`
+- `fastapi_common/fastapi_common_storage/oss_path_utils.py`
+
+#### 最低能力要求
+
+- 上传 bytes
+- 上传文本
+- 上传本地文件
+- 下载 bytes
+- 下载到本地临时文件
+- 判断对象是否存在
+- 生成 presigned URL
+- 统一返回 object key / url
+
+#### 完成标准
+
+- 规则和文档两条链都能复用同一套 OSS 接口
+- bridge 代码中不再直接写 `urlopen`
+
+### M1-3 统一 OSS 路径生成工具
+
+#### 目标
+
+把文档中约定的路径规范落实为代码工具，避免业务层散写路径字符串。
+
+#### 路径规范
+
+```text
+bdocs/{region}/{type_code}/{doc_id}/{version}/{file_role}.{ext}
+artifacts/{region}/{run_id}/{artifact_type}/{detail}.{ext}
+rules/{rule_type}/{version_no}/rules.yaml
+rules/{rule_type}/{version_no}/validation_report.json
+```
+
+#### 需要实现的方法
+
+- `BuildBusinessDocKey(...)`
+- `BuildArtifactKey(...)`
+- `BuildRuleYamlKey(...)`
+- `BuildRuleValidationReportKey(...)`
+
+#### 完成标准
+
+- 上传文档、上传规则、记录产物时统一生成 key
+- 路径规范不再散落在业务代码中
+
+### M1-4 接管当前 bridge 下载逻辑
+
+#### 目标
+
+把 bridge 中当前临时下载逻辑接到统一 OSS 服务。
+
+#### 需要修改的文件
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/fileSourceResolver.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ruleVersionResolver.py`
+
+#### 完成标准
+
+- 文档下载统一经 OSS client
+- 规则下载统一经 OSS client
+- 支持正式私有桶而不只依赖公开 HTTP/HTTPS
+
+---
+
+## M2：规则管理后端能力
+
+### M2-1 补规则服务接口
+
+#### 目标
+
+把规则服务从当前骨架扩展为完整规则生命周期服务。
+
+#### 建议能力
+
+- 查询规则集列表
+- 查询规则版本列表
+- 查询指定版本正文
+- 校验 YAML
+- 创建新规则版本
+- 发布规则版本
+- 回滚规则版本
+
+#### 需要修改或新增的文件
+
+- `fastapi_modules/fastapi_leaudit/services/ruleService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`
+
+#### 完成标准
+
+- Service 层接口稳定
+- 后续 controller 只做 DTO 拆值与返回
+
+### M2-2 补 DTO / VO / BO
+
+#### 目标
+
+为规则管理接口提供规范化入参与出参。
+
+#### 建议新增文件
+
+- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleVersionCreateDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleValidateDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/Dto/rulePublishDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/vo/ruleVersionVo.py`
+- `fastapi_modules/fastapi_leaudit/domian/vo/ruleContentVo.py`
+- `fastapi_modules/fastapi_leaudit/domian/bo/ruleVersionCreateBo.py`
+
+#### 完成标准
+
+- 字段统一 lowerCamelCase
+- Controller 只接 DTO
+- Service 返回 VO / BO
+
+### M2-3 实现规则校验服务
+
+#### 目标
+
+为在线编辑和发布提供保存前 / 发布前的双层校验能力。
+
+#### 校验层次
+
+##### 第一层：YAML 语法校验
+
+- 缩进
+- 基本结构
+- 能否解析
+
+##### 第二层：LeAudit DSL 语义校验
+
+- `metadata` 是否完整
+- `type_id` / `name` / `version` 是否有效
+- rule / extract / stage 结构是否合法
+- 字段引用是否一致
+- phase / risk / score / activate_if 是否符合 DSL 约束
+
+#### 建议新增文件
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ruleValidator.py`
+
+#### 完成标准
+
+- 非法 YAML 不能发布
+- 校验错误可返回给前端展示
+
+### M2-4 实现规则版本上传与落库
+
+#### 目标
+
+让规则版本真正以“OSS 存正文、DB 存索引”的方式保存。
+
+#### 处理步骤
+
+```text
+接收 YAML 文本
+  -> 语法校验
+  -> DSL 校验
+  -> 计算 sha256 / file_size
+  -> 生成 rules/{rule_type}/{version_no}/rules.yaml
+  -> 上传 OSS
+  -> 写 leaudit_rule_versions
+  -> 需要时写 validation_report.json
+```
+
+#### 需要修改的文件
+
+- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`
+- `fastapi_common/fastapi_common_storage/oss_path_utils.py`
+
+#### 完成标准
+
+- `leaudit_rule_versions` 中完整记录：
+  - `oss_url`
+  - `file_sha256`
+  - `file_size`
+  - `metadata_type_id`
+  - `metadata_name`
+  - `metadata_version`
+
+### M2-5 实现发布与回滚
+
+#### 目标
+
+通过切换 `leaudit_rule_sets.current_version_id` 管理当前生效版本。
+
+#### 处理要求
+
+- 发布时更新当前生效版本
+- 回滚时切换回历史版本
+- 保留审计信息
+- 不影响历史 run 对旧版本的追溯
+
+#### 完成标准
+
+- 新 run 会自动使用新版本
+- 老 run 仍保留历史规则来源
+
+### M2-6 暴露规则管理控制器
+
+#### 目标
+
+为后续规则编辑页面提供 API。
+
+#### 建议新增文件
+
+- `fastapi_modules/fastapi_leaudit/controllers/ruleController.py`
+
+#### 建议接口
+
+- `GET /api/leaudit/rule-sets`
+- `GET /api/leaudit/rule-sets/{ruleType}/versions`
+- `GET /api/leaudit/rule-versions/{versionId}/content`
+- `POST /api/leaudit/rule-sets/{ruleType}/validate`
+- `POST /api/leaudit/rule-sets/{ruleType}/versions`
+- `POST /api/leaudit/rule-sets/{ruleType}/publish`
+- `POST /api/leaudit/rule-sets/{ruleType}/rollback`
+
+#### 完成标准
+
+- 前端可直接基于这些接口做查看、编辑、发布、回滚
+- 响应统一走 `Result`
+
+---
+
+## M3：执行链正式化与持久化补齐
+
+### M3-1 文档来源解析正式接入 OSS 服务
+
+#### 目标
+
+把 `fileSourceResolver.py` 从临时 URL 下载升级为正式存储接入。
+
+#### 处理优先级
+
+1. 优先 `localPath`
+2. 否则走 `ossUrl` / object key
+3. 落本地临时文件或 bytes 交给执行链
+
+#### 需要修改的文件
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/fileSourceResolver.py`
+
+#### 完成标准
+
+- 文档来源解析不再直接依赖 `urllib`
+- 后续换 OSS 实现无需改业务层
+
+### M3-2 规则来源解析正式接入 OSS 服务
+
+#### 目标
+
+把 `ruleVersionResolver.py` 升级为正式的规则版本来源解析器。
+
+#### 标准链路
+
+```text
+run_id
+  -> leaudit_audit_runs.rule_version_id
+  -> leaudit_audit_runs.rule_source_oss_url
+  -> 下载规则 YAML
+  -> sha256 校验
+  -> 写本地临时 YAML
+  -> RulesLoader.load(local_path)
+```
+
+#### 需要修改的文件
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ruleVersionResolver.py`
+
+#### 完成标准
+
+- 执行优先绑定具体规则版本
+- 不再主要依赖 `_TYPE_ID_RULES_MAP`
+
+### M3-3 补全运行结果持久化
+
+#### 目标
+
+把 NativeRunner 当前未落库的数据继续补齐。
+
+#### 需要补的内容
+
+- `leaudit_run_metrics`
+- `leaudit_run_errors`
+- `rescue_outcomes`
+- `finishedAt`
+- `resultStatus`
+- 必要的 artifact 索引
+
+#### 需要修改的文件
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/nativeRunner.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
+
+#### 完成标准
+
+- 一次 run 的关键结果和错误都能追溯
+- 不再只落 `ocr/extract/evaluate/rule_results`
+
+### M3-4 明确 run 状态机
+
+#### 目标
+
+统一 run 的状态与 phase 更新逻辑。
+
+#### 建议状态
+
+- `pending`
+- `running`
+- `completed`
+- `failed`
+
+#### 需要修改的文件
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
+
+#### 完成标准
+
+- 前端轮询可看到真实运行进度
+- 失败时能准确落状态和错误信息
+
+---
+
+## M4：全流程联调与验收
+
+### M4-1 梳理上传入口
+
+#### 目标
+
+确认现有上传能力到底走哪些 controller / service，以及上传后是否已形成：
+
+- `leaudit_documents`
+- `leaudit_document_files`
+- 文件来源记录
+- 当前活跃版本标记
+
+#### 需要重点检查的位置
+
+- `fastapi_modules/fastapi_leaudit/controllers/`
+- `fastapi_modules/fastapi_leaudit/services/`
+- 文档上传相关 service / controller
+
+#### 完成标准
+
+- 明确上传后如何进入评查系统
+
+### M4-2 接通上传后触发评查
+
+#### 目标
+
+形成稳定用户操作路径。
+
+#### 最小可接受路径
+
+##### 路径 A：两步操作
+
+```text
+上传文档
+  -> 手工点击触发评查
+```
+
+##### 路径 B：一步自动触发
+
+```text
+上传文档
+  -> 自动创建 run 并触发评查
+```
+
+#### 完成标准
+
+- 至少有一种路径可稳定跑通
+
+### M4-3 补结果查询展示所需字段
+
+#### 目标
+
+确保前端能拿到完整结果展示数据。
+
+#### 至少要能查到
+
+- run 基本状态
+- 总分 / 通过数 / 失败数 / 跳过数
+- 规则明细
+- 失败原因
+- 产物地址（如有）
+
+#### 需要重点修改的文件
+
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
+- 对应 controller / VO
+
+#### 完成标准
+
+- 前端拿 `runId` 可以完成结果展示
+
+### M4-4 准备联调样例
+
+#### 目标
+
+准备一套可重复使用的联调数据。
+
+#### 至少需要
+
+- 1 份真实文档样例
+- 1 条有效规则绑定
+- 1 份可访问规则 YAML
+- 1 套可运行配置
+
+#### 完成标准
+
+- 能稳定复现成功链路
+- 能稳定复现失败链路
+
+### M4-5 完成一次真实 E2E 验证
+
+#### 验证目标链
+
+```text
+上传文档
+  -> document / file 入库
+  -> 文件可下载
+  -> 规则 YAML 可下载
+  -> Native AuditCtx 执行
+  -> OCR / 抽取 / 评查完成
+  -> 结果写回 DB
+  -> 查询结果成功
+```
+
+#### 完成标准
+
+- 至少成功跑通 1 个真实样例
+- 至少验证 1 个失败样例
+- 形成一份验收记录文档
+
+---
+
+## 推荐实施顺序
+
+本轮开发建议严格按以下顺序执行：
+
+### 第一阶段：先做 M1
+
+- M1-1 配置模型
+- M1-2 OSS client
+- M1-3 路径工具
+- M1-4 接管现有 bridge 下载逻辑
+
+原因：
+
+- 这是后续规则管理和全流程联调的共同底座
+
+### 第二阶段：做 M2
+
+- M2-1 规则服务接口
+- M2-2 DTO / VO / BO
+- M2-3 规则校验
+- M2-4 新版本上传
+- M2-5 发布 / 回滚
+- M2-6 控制器接口
+
+原因：
+
+- 先把规则后端能力做实，再给前端接口
+
+### 第三阶段：做 M3
+
+- M3-1 文档来源正式接入
+- M3-2 规则来源正式接入
+- M3-3 持久化补齐
+- M3-4 run 状态机
+
+原因：
+
+- 这是把“能跑”升级为“可维护、可观察”
+
+### 第四阶段：做 M4
+
+- M4-1 上传入口梳理
+- M4-2 上传后触发
+- M4-3 结果查询补齐
+- M4-4 样例准备
+- M4-5 E2E 联调
+
+原因：
+
+- 最后做整体验收，避免中途反复返工
+
+---
+
+## 高优先级文件清单
+
+### 一定会修改的文件
+
+- `fastapi_admin/config/_settings.py`
+- `fastapi_admin/config/__init__.pyi`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/fileSourceResolver.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ruleVersionResolver.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/nativeRunner.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
+- `fastapi_modules/fastapi_leaudit/services/ruleService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
+
+### 大概率新增的文件
+
+- `fastapi_common/fastapi_common_storage/oss_client.py`
+- `fastapi_common/fastapi_common_storage/oss_path_utils.py`
+- `fastapi_modules/fastapi_leaudit/services/ossService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/ossServiceImpl.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`
+- `fastapi_modules/fastapi_leaudit/controllers/ruleController.py`
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ruleValidator.py`
+- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleVersionCreateDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleValidateDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/Dto/rulePublishDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/vo/ruleVersionVo.py`
+- `fastapi_modules/fastapi_leaudit/domian/vo/ruleContentVo.py`
+- `fastapi_modules/fastapi_leaudit/domian/bo/ruleVersionCreateBo.py`
+
+---
+
+## 验收口径
+
+### M1 验收
+
+- 文档和规则都经统一 OSS 服务访问
+- bridge 中不再散落临时下载逻辑
+
+### M2 验收
+
+- 可以新建规则版本、读内容、发布、回滚
+- YAML 正式存 OSS，元数据正式存 DB
+
+### M3 验收
+
+- run 与 rule version 绑定关系稳定
+- 运行结果持久化完整
+- 运行状态与 phase 可查询
+
+### M4 验收
+
+- 真实上传到评查结束可跑通
+- 查询结果成功
+- 有联调 / 验收记录
+
+---
+
+## 实施结论
+
+本轮开发不再继续扩散平台手写评查逻辑，而是坚持以下原则：
+
+- `leaudit` 核心不改
+- 平台负责 DB / OSS / API / 权限 / 任务入口
+- bridge 负责把平台语义转换成原生 `AuditCtx` 输入
+- 文档与规则都采用“OSS 真源 + 数据库存索引 + 本地临时文件执行”的模式
+
+按本计划推进后，既能保证当前原生执行链继续稳定，也能为后续 YAML 在线编辑界面和完整评查业务闭环打下正式基础。