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,711 @@
+# 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 + 校验/发布/回滚`
+
+也就是说：
+
+- **第一优先级是评查主链**
+- **第二优先级是规则执行链**
+- **第三优先级才是规则编辑后台**
+
+这样开发成本最低，验证路径也最清晰。