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

752 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 背景
当前 `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
#### 完成标准
- 明确上传后如何进入评查系统
#### 当前进展（2026-04-28）
- 已确认当前仓库原先没有现成的 LeAudit 文档上传入口
- 已补最小可用上传接口：`POST /upload`
- 已新增上传服务链：
- `DocumentController`
- `IDocumentService`
- `DocumentServiceImpl`
- 当前上传链已实现：
```text
multipart file
-> 上传 OSS
-> 写 leaudit_documents
-> 写 leaudit_document_files
-> autoRun=true 时直接进入 AuditServiceImpl.Run()
```
### M4-2 接通上传后触发评查
#### 目标
形成稳定用户操作路径。
#### 最小可接受路径
##### 路径 A：两步操作
```text
上传文档
-> 手工点击触发评查
```
##### 路径 B：一步自动触发
```text
上传文档
-> 自动创建 run 并触发评查
```
#### 完成标准
- 至少有一种路径可稳定跑通
#### 当前进展（2026-04-28）
- 路径 A“上传后手工触发评查”已具备
- 路径 B“一步自动触发”已补最小实现：
```text
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 验证
#### 验证目标链
```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 在线编辑界面和完整评查业务闭环打下正式基础。
Reference in New Issue View Git Blame Copy Permalink