# LeAudit 规则链路实施总方案

> 说明：这份文档是当前 `docs/规则编辑/` 目录的主实施文档。
> 原 `开发任务拆解清单.md` 的任务顺序、文件清单与验收口径，后续统一以本文件为准。
> 原 `跑通全流程所需准备项.md` 的能力清单，也统一归并到本文件维护。
> 原 `yaml规则在线编辑设计.md` 与 `worker并发执行改造方案.md` 的核心口径，也统一归并到本文件维护。

## 背景

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