TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
wren-dev
leaudit-platform-backend/docs/文档图片质量校验模块/文档图片质量校验模块-页码级模糊预警简化版.md
T

7.8 KiB
Raw Permalink Blame History

文档图片质量校验模块定制开发计划

1. 目标收口

本次版本只做“页码级模糊预警”，不做图片级定位。

系统最终只需要给出这类提示：

  • 第3页疑似模糊
  • 第2页、第5页疑似模糊
  • 第4页建议重拍

不需要输出：

  • 第几张图片
  • 图片框选位置
  • bbox
  • 裁剪图回显
  • OCR 图块级关联

这次方案的核心原则只有两条：

  • 只做预警，不阻断主流程
  • 只做到页码，不追求图级精确定位

2. 与当前 OCR / 评查链路的关系

本模块必须独立于当前 OCR 抽取、评查流程之外。

现有主流程保持不变：

  1. 用户上传文档
  2. 文档进入 OCR / 抽取 / 评查 pipeline
  3. 系统继续正常落库、展示、评查

新增流程只是一条旁路异步任务：

  1. 文档上传成功
  2. 异步投递“页级图片质量检测任务”
  3. 后台生成页码级预警结果
  4. 前端在列表页、详情页显示提示

明确约束：

  • 图片质量检测失败，不影响上传
  • 图片质量检测超时，不影响 OCR
  • 图片质量检测发现模糊页，不影响评查
  • 整个模块只作为 warning，不参与主流程 gate

3. 检测范围与判定结果

3.1 启用策略

建议保留三层控制：

  • 全局总开关
  • 文档类型维度开关
  • 地区维度开关

判定顺序：

  1. 先看全局总开关
  2. 再看文档类型是否命中
  3. 再看地区是否命中

只要任一环节不命中，就直接跳过。

3.2 文档类型跳过策略

纯文本型文档直接跳过，不做页级图片质量检测。

适用检测的主要是：

  • PDF 扫描件
  • 图片型案卷
  • 转 PDF 后包含大量扫描页的 doc/docx/wps

不适合检测的纯文本类文档，直接标记为 skipped。

3.3 结果分档

仍保留三档结果，便于后续扩展：

  • pass：通过
  • review：疑似模糊，待人工确认
  • reject：不通过，建议重拍

前端展示文案建议直接对应：

  • 通过
  • 疑似模糊
  • 建议重拍

4. 定位策略

这次不做“定位到哪张图片”，只做“定位到第几页”。

也就是说：

  • PDF：直接逐页检测
  • 图片：按单页处理
  • doc/docx/wps：统一先转为稳定的页级 PDF，再逐页检测

最后只返回页码列表，例如：

  • pages=[2,5,8]
  • warningText=第2页、第5页、第8页疑似模糊

这样实现最稳，也最符合你现在已经确认的需求收口。

5. 当前仓库的落点

按目前仓库结构，模块建议挂在 fastapi_leaudit 下，和当前评查链路平行存在。

当前新增代码落点如下：

  • fastapi_modules/fastapi_leaudit/domian/vo/pageQualityVo.py
  • fastapi_modules/fastapi_leaudit/services/pageQualityService.py
  • fastapi_modules/fastapi_leaudit/services/impl/pageQualityServiceImpl.py
  • fastapi_modules/fastapi_leaudit/controllers/pageQualityController.py
  • fastapi_modules/fastapi_leaudit/page_quality/tasks.py
  • fastapi_modules/fastapi_leaudit/page_quality/runner.py
  • scripts/创建sql/schema_add_page_quality_module.sql
  • scripts/创建sql/seed_page_quality_permissions.sql
  • scripts/创建sql/seed_page_quality_routes.sql

6. 当前实现方案

6.1 数据表

当前方案只保留两张表，足够支撑第一版：

leaudit_page_quality_runs

  • 记录一次文档级检测任务
  • 保存任务状态、总页数、问题页统计、摘要状态

leaudit_page_quality_results

  • 记录每一页的检测结果
  • 每页只保留一条结果

这版不新增图片明细表，不做图级索引。

6.2 Service 职责

PageQualityServiceImpl

  • DispatchForDocument
    • 创建 run
    • 投递 Celery 异步任务
  • ExecuteRun
    • 读取文件
    • 转为页级图片
    • 逐页检测
    • 落库结果
    • 汇总文档级状态
  • GetDocumentSummary
    • 返回文档的页级检测摘要
  • GetDocumentDetail
    • 返回页级问题页详情
  • RecheckDocument
    • 手工重跑

6.3 Controller 路由

当前建议保留 3 个接口：

  • GET /documents/{DocumentId}/page-quality/summary
  • GET /documents/{DocumentId}/page-quality
  • POST /documents/{DocumentId}/page-quality/recheck

这样够前端做：

  • 列表轻提示
  • 详情展开
  • 手工重检

6.4 Celery 任务链路

当前任务入口：

  • leaudit.page_quality.process_document

队列配置：

  • LEAUDIT_PAGE_QUALITY_QUEUE_NORMAL
  • LEAUDIT_PAGE_QUALITY_QUEUE_URGENT

它和当前 OCR / 评查队列分开，避免互相影响。

7. 与现有 DocumentService 的集成方式

按当前项目代码风格，集成点放在 DocumentServiceImpl。

7.1 上传成功后自动触发

接入点：

  • DocumentServiceImpl.Upload

处理方式：

  • 文档主文件落库成功后
  • 使用 try/except 异步投递页级质量检测
  • 失败只记日志，不抛阻断异常

7.2 补充附件后重跑

接入点：

  • DocumentServiceImpl.AppendAttachments

处理方式：

  • 附件写入完成后
  • 触发一次 Force=True 的重跑任务
  • 仍然不影响主链路返回

7.3 文档接口回填摘要

当前需要在这些返回对象上挂页级质量摘要字段：

  • DocumentUploadVO
  • DocumentListItemVO
  • DocumentStatusItemVO
  • DocumentDetailVO

建议统一补这些字段：

  • pageQualityRunId
  • pageQualityRunStatus
  • pageQualitySummaryStatus
  • pageQualityIssueCount
  • pageQualityWarningText

详情页额外补：

  • pageQualitySummary

8. 页级检测执行逻辑

8.1 输入统一

统一转成“按页检测”的输入：

  • pageNum
  • pageImageBytes

这样后面的检测器不关心文件来源，只关心这一页图像本身。

8.2 文件处理策略

建议如下：

  • pdf：直接渲染每页
  • png/jpg/jpeg/bmp/tiff/webp：按 1 页处理
  • doc/docx/wps：先转 PDF，再逐页渲染

8.3 并发策略

第一版可以做“页级并发”，但不建议过度并发。

建议原则：

  • 只在单文档内部做有限并发
  • 队列级别仍由 Celery 控制
  • 优先保证稳定，不追求极限吞吐

8.4 检测结果汇总

汇总规则固定如下：

  • 只要有 reject 页，文档摘要状态就是 reject
  • 否则只要有 review 页，文档摘要状态就是 review
  • 否则是 pass

页码列表只展示 review/reject 页。

9. 前端改造建议

这次前端不要做复杂交互，保持轻量。

9.1 列表页

增加一个“图片质量”状态展示位：

  • 通过
  • 疑似模糊
  • 建议重拍

如果已有问题页，hover 或轻提示展示：

  • 第2页、第5页疑似模糊

9.2 详情页

增加一个“图片质量预警”卡片即可。

卡片内容只展示：

  • 状态
  • 问题页数
  • 页码提示文案
  • 手工重检按钮

第一版不要做跳图，不要做页内图片定位。

9.3 上传完成提示

上传返回里如果已经拿到 run 信息，可以轻提示：

  • 图片质量检测中

等异步任务完成后，再通过详情或列表刷新展示结果。

10. 第一版不做的内容

明确不纳入本次版本：

  • 图片级定位
  • 第几张图模糊
  • OCR visual_manifest 细粒度关联
  • 页内坐标框
  • 图片裁剪回显
  • 基于模糊结果阻断上传
  • 基于模糊结果阻断评查
  • 基于模糊结果自动退件

11. 当前版本的实现价值

这一版的好处很明确：

  • 复杂度大幅降低
  • 能快速上线验证业务价值
  • 不改现有 OCR / 评查主链核心逻辑
  • 前后端联调成本低
  • 后续如果业务真要升级，再往图级定位扩展也有落点

12. 最终结论

按当前仓库和你已经确认的需求，最合适的落地方案就是：

  • 独立页级图片质量检测模块
  • 只做页码级模糊预警
  • 异步执行
  • 不阻断主流程
  • 列表页和详情页只展示“第几页疑似模糊 / 建议重拍”

这就是第一版最稳、最省、最适合推进开发的模块计划。

Reference in New Issue View Git Blame Copy Permalink