TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e738398eb6af306364a6aa28e114788af32cdd37
leaudit-platform-backend/docs/规则编辑/开发任务拆解清单.md
T

19 KiB
Raw Blame History

LeAudit 开发任务拆解清单

1. 目标

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

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

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

上传文档
  → 获取文件真源
  → 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：先打通最小评查闭环

目标：

上传文档
  → 创建 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，而是逐步过渡到：

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

目标：

文档类型
  → 绑定表
  → 规则集
  → 当前版本
  → 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 + 校验/发布/回滚

也就是说：

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

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

Reference in New Issue View Git Blame Copy Permalink