leaudit-platform-backend/docs/规则编辑/开发任务拆解清单.md

# LeAudit 开发任务拆解清单

## 1. 目标

基于以下两份文档，进一步拆出一份可执行的开发任务清单，并尽量精确到建议修改文件：

- `docs/规则编辑/yaml规则在线编辑设计.md`
- `docs/规则编辑/跑通全流程所需准备项.md`

本清单覆盖的目标不是单点“规则编辑”，而是完整业务链路：

```text
上传文档
  → 获取文件真源
  → OCR
  → 抽取
  → 评查
  → 结果落库
  → 查询运行状态 / 结果
  → 再扩展到 YAML 在线编辑 / 发布 / 回滚
```

---

## 2. 当前代码现状摘要

在开始任务前，先明确当前代码的真实状态。

> 2026-04-27 补充结论：结合 `/home/wren-dev/Porject/leaudit/src` 源码确认，
> 当前 `leaudit` 的正式执行入口应视为：
> `AuditCtx` + `AuditService.audit(ctx)`。
> 因此本清单中的后续任务，默认都以“保留 Bridge，但禁止平台自己重写主流程编排”为前提。

### 2.1 已有骨架

- 评查控制器：
  - `fastapi_modules/fastapi_leaudit/controllers/auditController.py`
- 评查服务接口/实现：
  - `fastapi_modules/fastapi_leaudit/services/auditService.py`
  - `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
- bridge 层：
  - `fastapi_modules/fastapi_leaudit/leaudit_bridge/pipeline.py`
  - `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
  - `fastapi_modules/fastapi_leaudit/leaudit_bridge/rules_loader.py`
  - `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
  - `fastapi_modules/fastapi_leaudit/leaudit_bridge/ctx_builder.py`
- 模型：
  - `fastapi_modules/fastapi_leaudit/models/leauditDocument.py`
  - `fastapi_modules/fastapi_leaudit/models/leauditDocumentFile.py`
  - `fastapi_modules/fastapi_leaudit/models/leauditAuditRun.py`
- 规则服务接口骨架：
  - `fastapi_modules/fastapi_leaudit/services/ruleService.py`
  - `fastapi_modules/fastapi_leaudit/domian/vo/ruleVo.py`

### 2.2 当前主要缺口

- `AuditServiceImpl.Run()` 已可创建 run 并触发 NativeRunner 任务
- `GetResult()` 已可查询 `leaudit_rule_results`
- 规则文件主链已开始支持 `run -> rule_version -> oss_url -> 本地临时 YAML`
- `tasks.py` 仍保留 `LEAUDIT_RULES_DIR` 和 `_TYPE_ID_RULES_MAP` 作为 fallback
- 尚未看到规则编辑控制器与 `RuleServiceImpl`
- 尚未形成统一 OSS 文件服务
- 结果写入仍有“按 document_id 找最新 run”的简化逻辑

因此，任务拆解应该分两层：

- **P0：先把上传 → OCR → 抽取 → 评查 → 查询打通**
- **P1/P2：再把规则 OSS 化、版本化、在线编辑化**

---

## 3. 分阶段开发任务清单

## P0：先打通最小评查闭环

目标：

```text
上传文档
  → 创建 document / file / run
  → bridge 执行 OCR / 抽取 / 评查
  → 落库
  → 查到 run 状态与结果
```

---

### P0-1：补齐评查服务入口

#### 任务说明

把 `POST /api/audit/run` 从“只抛异常”改成真正可执行的评查入口。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/services/auditService.py`
- `fastapi_modules/fastapi_leaudit/domian/Dto/auditDto.py`
- `fastapi_modules/fastapi_leaudit/domian/vo/auditVo.py`

#### 具体工作

- 在 `Run()` 中完成：
  - 校验文档是否存在
  - 查当前可执行文件版本
  - 计算 `run_no`
  - 创建 `leaudit_audit_runs`
  - 调用 `dispatch_leaudit_task()`
  - 返回 `AuditRunVO`
- 调整 `IAuditService.Run()` 的接口定义，使其与实现参数一致
- 如有必要，为 `AuditRunDTO` 增加可选字段：
  - `documentFileId`
  - `force`
  - `ruleType`
  - `ruleVersionId`（可选，便于指定版本重跑）

#### 产出目标

- 调用 `/api/audit/run` 不再报 “Celery 任务集成待实现”
- 至少能创建 run 并触发 bridge 层执行

---

### P0-2：补齐 run 创建与状态更新逻辑

#### 任务说明

把 run 作为整条链的中心对象，保证每次执行都能明确追踪。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/models/leauditAuditRun.py`
- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`

#### 具体工作

- 在触发评查前创建 `leaudit_audit_runs`
- 明确 run 初始字段：
  - `status=pending`
  - `phase=normalize` 或空
  - `startedAt`
  - `documentFileId`
  - `ruleSetId`
  - `ruleVersionId`
- 执行链中显式传递 `run_id`
- `storage_adapter.py` 所有落库方法改为：
  - 不再“按 `document_id` 查最新 run”
  - 统一显式使用 `run_id`

#### 产出目标

- 所有结果写入能严格绑定到唯一 `run_id`
- 避免多次重跑 / 并发时结果串写

---

### P0-3：补齐文件输入链

#### 任务说明

在执行 OCR 前，明确“这次评查使用哪一个文件”。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/models/leauditDocument.py`
- `fastapi_modules/fastapi_leaudit/models/leauditDocumentFile.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ctx_builder.py`
- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`

#### 建议新增

- `fastapi_modules/fastapi_leaudit/services/documentService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`
  或
- `fastapi_modules/fastapi_leaudit/services/fileService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/fileServiceImpl.py`

#### 具体工作

- 增加“获取当前有效文件”的服务方法
- 根据 `document_id` 找到当前激活的 `leaudit_document_files`
- 如果文件在 OSS，先下载到本地临时路径
- 给 pipeline 提供稳定的 `file_path`

#### 产出目标

- 评查入口不依赖调用方直接传原始字节
- 可以从数据库+文件真源独立还原执行输入

---

### P0-4：打通 bridge 任务入口

#### 任务说明

让 `dispatch_leaudit_task()` 真正成为评查执行入口，而不是演示性同步封装。
但注意：这里的“执行入口”不是继续扩写平台自编排 pipeline，而是逐步过渡到：

```text
build AuditCtx
  → call AuditService.audit(ctx)
  → persist ctx outputs
```

#### 需要修改

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/__init__.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/pipeline.py`

#### 建议新增

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/audit_ctx_builder.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/audit_service_factory.py`

#### 具体工作

- 统一 `dispatch_leaudit_task()` 的入参：
  - `run_id`
  - `document_id`
  - `document_file_id`
  - `rules_path` 或 `rule_version_id`
  - 可选 `trigger_user_id`
- 逐步去掉 `source_port` 作为主上下文依赖
- 允许先同步执行，后续再切 Celery
- 逐步让 `pipeline.py` 退化为薄包装层，而不是 7 阶段自编排器
- 在 bridge 内部统一完成：
  - `AuditServices` 构造
  - `AuditConfig` 构造
  - 原生 `AuditCtx` 构造
  - `AuditService.audit(ctx)` 调用

#### 产出目标

- 业务层只调一个稳定入口
- bridge 层掌控实际执行上下文
- 主流程编排回归 `leaudit` 原生服务层

---

### P0-5：补齐结果查询接口

#### 任务说明

不仅要能跑，还要能看到结果。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/controllers/auditController.py`
- `fastapi_modules/fastapi_leaudit/domian/vo/auditVo.py`

#### 具体工作

- `GetRunStatus()` 查询真实 run 状态
- `GetResult()` 从以下表联合查询：
  - `leaudit_audit_runs`
  - `leaudit_rule_results`
  - 可选 `leaudit_field_results`
- 把 `rules=[]` 改成真实规则级返回
- 如有必要，为 `AuditResultVO` 增加：
  - `timing`
  - `fields`
  - `errors`

#### 产出目标

- `/api/audit/result/{RunId}` 能返回真实评查结果

---

### P0-6：补齐结果落库结构

#### 任务说明

当前 `StorageAdapter` 已有雏形，但还需要工程化加固。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/result_adapter.py`

#### 具体工作

- 所有保存方法显式接收 `run_id`
- 补 `run_metrics` 写入
- 补 `run_errors` 写入
- 梳理 `artifacts` 与 `field_results` 的最小必要字段
- 保持 `rule_results` 与 `AuditResultVO` 的结构一致

#### 产出目标

- 结果写入不再依赖“最新 run”猜测
- 后续前端查询更稳定

---

## P1：把规则执行链切到 OSS + DB

目标：

```text
文档类型
  → 绑定表
  → 规则集
  → 当前版本
  → OSS YAML
  → 下载本地临时文件
  → leaudit 执行
```

---

### P1-1：补规则读取服务

#### 任务说明

把规则加载从“本地目录路径”升级成“DB + OSS + 临时文件”。

#### 当前状态

这一项已经完成第一阶段落地：

- `auditServiceImpl.py` 会在建 run 时锁定 `ruleVersionId` 与 `ruleSourceOssUrl`
- `tasks.py` 会优先按 `run_id` 解析规则来源
- `ruleVersionResolver.py` 会把 OSS YAML 下载到本地临时文件
- `RulesLoader.load(local_path)` 已接入执行链

当前剩余工作已经从“能不能执行”变成“如何把上传 / 发布 / 缓存 / 回收做完整”。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/nativeRunner.py`
- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`

#### 建议新增

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ruleVersionResolver.py`

#### 具体工作

- 根据 run 锁定的 `rule_version_id` / `rule_source_oss_url` 解析规则来源
- 下载 YAML 到本地临时文件
- 校验 `rule_source_sha256`
- 调 `load_rules_file(local_path)`
- 继续保留本地 `rules/` 作为 fallback

#### 产出目标

- 执行时优先走 run 绑定规则版本，而不是 `_TYPE_ID_RULES_MAP`
- 原生 `AuditCtx.rules_file` 由 bridge 正式注入，而不是平台手工绕过服务编排层

---

### P1-2：补统一 OSS 文件服务

#### 任务说明

项目当前有 OSS 配置，但缺少统一文件服务。

#### 需要修改

- `fastapi_admin/config/_settings.py`（仅在配置不够时）

#### 建议新增

- `fastapi_common/fastapi_common_storage/__init__.py`
- `fastapi_common/fastapi_common_storage/oss_client.py`
- `fastapi_common/fastapi_common_storage/oss_path_utils.py`

如果不想放到 `fastapi_common/`，也可以先放：

- `fastapi_modules/fastapi_leaudit/services/ossService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ossServiceImpl.py`

#### 具体工作

- 提供统一方法：
  - 上传文件到 OSS
  - 下载到本地临时文件
  - 计算 / 校验 sha256
  - 删除临时文件
- 同时兼容：
  - 规则文件
  - 原始文档
  - 评查产物

#### 产出目标

- 文档文件和规则文件都可以共用一套对象存储服务

---

### P1-3：补规则版本与绑定的查询模型

#### 任务说明

当前代码里还没有看到对应规则表的 ORM / 查询对象，后续查询会比较痛苦。

#### 建议新增

- `fastapi_modules/fastapi_leaudit/models/leauditRuleSet.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRuleVersion.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRuleTypeBinding.py`
- 更新 `fastapi_modules/fastapi_leaudit/models/__init__.py`

#### 具体工作

- 为规则集、规则版本、绑定表建立 ORM
- 后续服务层不必到处手写 SQL

#### 产出目标

- 规则管理服务、规则解析服务都能清晰建模

---

## P2：开放 YAML 在线编辑 / 发布 / 回滚

目标：

让规则成为后台可管理资产，而不是服务器上的裸文件。

---

### P2-1：补规则控制器与服务实现

#### 任务说明

当前只有 `IRuleService` 接口，需要真正落地规则后台。

#### 需要修改

- `fastapi_modules/fastapi_leaudit/services/ruleService.py`
- `fastapi_modules/fastapi_leaudit/domian/vo/ruleVo.py`

#### 建议新增

- `fastapi_modules/fastapi_leaudit/controllers/ruleController.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleDto.py`

#### 具体工作

- 完成接口：
  - 列表
  - 版本历史
  - 查看内容
  - 保存版本
  - 校验
  - 发布
  - 回滚
- 为 controller 增加路由

#### 产出目标

- 后台可以真正管理规则

---

### P2-2：补规则内容查看/保存接口

#### 建议新增

- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleContentDto.py`

#### 具体工作

- 定义：
  - 保存 YAML 文本请求 DTO
  - 规则校验响应 VO
  - 规则内容响应 VO
- 从 OSS 读回内容展示给前端
- 新版本保存时先写 OSS，再写 DB

#### 产出目标

- 前端可以拿到 YAML 文本并保存新版本

---

### P2-3：补 YAML 语法校验 + DSL 语义校验

#### 建议新增

- `fastapi_modules/fastapi_leaudit/services/ruleValidationService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ruleValidationServiceImpl.py`

#### 具体工作

- YAML 解析校验
- `leaudit` DSL schema 校验
- 提取 metadata 快照
- 形成标准错误列表

#### 产出目标

- 发布前可拦截坏规则

---

### P2-4：补发布、回滚、审计

#### 需要修改

- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`

#### 建议新增

- `fastapi_modules/fastapi_leaudit/models/leauditRulePublishLog.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRuleValidationLog.py`

如果暂时不建 ORM，也至少需要：

- 对应 SQL migration / 建表脚本

#### 具体工作

- 发布时更新 `current_version_id`
- 写发布日志
- 回滚时写回滚日志
- 记录操作者与时间

#### 产出目标

- 规则变更具备可审计性

---

## P3：补平台级工程能力

目标：

让系统从“能跑”升级到“可持续运行”。

---

### P3-1：Celery / Redis 正式接入

#### 需要修改

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
- `fastapi_modules/fastapi_leaudit/tasks/__init__.py`
- `fastapi_admin/config/_settings.py`

#### 建议新增

- `fastapi_common/fastapi_common_cache/redis_pool.py`
- `fastapi_modules/fastapi_leaudit/tasks/celery_app.py`

#### 具体工作

- 同步任务改为异步分发
- 配置任务超时 / 重试 / 队列

---

### P3-2：规则缓存与发布失效

#### 需要修改

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/rules_loader.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`

#### 具体工作

- 规则缓存 key 改为 `rule_version_id` 或 `oss_url + sha256`
- 发布后清缓存
- 多 worker 时设计统一失效策略

---

### P3-3：结果增强与诊断能力

#### 需要修改

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`

#### 具体工作

- 完整落 `run_metrics`
- 完整落 `run_errors`
- 补 `rescue_outcomes`
- 前端可查看错误详情、阶段耗时

---

## 4. 建议新增文件总表

下面是我建议优先考虑新增的文件，便于你按模块建任务：

### 规则管理

- `fastapi_modules/fastapi_leaudit/controllers/ruleController.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/services/ruleValidationService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ruleValidationServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/services/ruleResolverService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/ruleResolverServiceImpl.py`
- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleDto.py`
- `fastapi_modules/fastapi_leaudit/domian/Dto/ruleContentDto.py`

### 规则 ORM

- `fastapi_modules/fastapi_leaudit/models/leauditRuleSet.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRuleVersion.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRuleTypeBinding.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRulePublishLog.py`
- `fastapi_modules/fastapi_leaudit/models/leauditRuleValidationLog.py`

### 文件与存储

- `fastapi_common/fastapi_common_storage/oss_client.py`
- `fastapi_common/fastapi_common_storage/oss_path_utils.py`

### 原生 AuditCtx 接入

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/audit_ctx_builder.py`
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/audit_service_factory.py`

### 文档执行输入

- `fastapi_modules/fastapi_leaudit/services/documentService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`

### 异步任务 / 缓存

- `fastapi_modules/fastapi_leaudit/tasks/celery_app.py`
- `fastapi_common/fastapi_common_cache/redis_pool.py`

---

## 5. 建议优先修改文件总表

如果按“先把主链跑通”的角度，最优先改的文件是：

1. `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
2. `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
3. `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py`
4. `fastapi_modules/fastapi_leaudit/leaudit_bridge/rules_loader.py`
5. `fastapi_modules/fastapi_leaudit/leaudit_bridge/ctx_builder.py`
6. `fastapi_modules/fastapi_leaudit/domian/vo/auditVo.py`
7. `fastapi_modules/fastapi_leaudit/services/ruleService.py`
8. `fastapi_modules/fastapi_leaudit/domian/vo/ruleVo.py`
9. `fastapi_modules/fastapi_leaudit/models/__init__.py`
10. `fastapi_admin/config/_settings.py`

---

## 6. 推荐执行顺序

如果按最稳妥的方式推进，我建议这样做：

### 第一阶段：只做主链闭环

- 改 `AuditServiceImpl`
- 改 `tasks.py`
- 新增 `audit_ctx_builder.py`
- 新增 `audit_service_factory.py`
- 改 `storage_adapter.py`
- 改 `GetResult()`

目标：先能跑通上传后评查与结果查询。

### 第二阶段：切规则到 OSS + DB

- 补规则 ORM
- 改 `rules_loader.py`
- 加 OSS 文件服务

目标：评查执行真正使用数据库发布的规则版本。

### 第三阶段：开放规则后台

- 加 `ruleController.py`
- 加 `RuleServiceImpl`
- 加校验服务
- 加发布/回滚日志

目标：前端可编辑、发布、回滚 YAML。

### 第四阶段：工程化增强

- Celery / Redis
- 缓存失效
- 审计
- metrics / errors / rescue

目标：从“能跑”变成“可运营”。

---

## 7. 一句话结论

如果你要的是“基于当前代码库，把功能拆成能开发的任务”，那么真正的主线不是先做编辑器，而是：

1. 先把 `auditServiceImpl + bridge + storageAdapter` 打通  
2. 再把 `rules_loader` 从本地目录切到 `OSS + DB`  
3. 最后再做 `ruleController + RuleServiceImpl + 校验/发布/回滚`

也就是说：

- **第一优先级是评查主链**
- **第二优先级是规则执行链**
- **第三优先级才是规则编辑后台**

这样开发成本最低，验证路径也最清晰。