TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e738398eb6af306364a6aa28e114788af32cdd37
leaudit-platform-backend/docs/规则编辑/统一OSS与规则管理实施计划.md
T
wren e738398eb6 feat: wire native leaudit upload flow
2026-04-28 16:53:16 +08:00

18 KiB
Raw Blame History

背景

当前 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：打通完整评查流程

跑通最小完整业务闭环：

上传文档
  -> 文档入库
  -> 文件入 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 路径生成工具

目标

把文档中约定的路径规范落实为代码工具，避免业务层散写路径字符串。

路径规范

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 存索引”的方式保存。

处理步骤

接收 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 升级为正式的规则版本来源解析器。

标准链路

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

完成标准

  • 明确上传后如何进入评查系统

当前进展（2026-04-28）

  • 已确认当前仓库原先没有现成的 LeAudit 文档上传入口
  • 已补最小可用上传接口：POST /upload
  • 已新增上传服务链：
    • DocumentController
    • IDocumentService
    • DocumentServiceImpl
  • 当前上传链已实现：
multipart file
  -> 上传 OSS
  -> 写 leaudit_documents
  -> 写 leaudit_document_files
  -> autoRun=true 时直接进入 AuditServiceImpl.Run()

M4-2 接通上传后触发评查

目标

形成稳定用户操作路径。

最小可接受路径

路径 A：两步操作
上传文档
  -> 手工点击触发评查
路径 B：一步自动触发
上传文档
  -> 自动创建 run 并触发评查

完成标准

  • 至少有一种路径可稳定跑通

当前进展（2026-04-28）

  • 路径 A“上传后手工触发评查”已具备
  • 路径 B“一步自动触发”已补最小实现：
POST /upload
  -> autoRun=true
  -> DocumentServiceImpl.Upload()
  -> AuditServiceImpl.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 验证

验证目标链

上传文档
  -> 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 在线编辑界面和完整评查业务闭环打下正式基础。

Reference in New Issue View Git Blame Copy Permalink