wren
351 lines
7.8 KiB
Markdown
351 lines
7.8 KiB
Markdown
# 文档图片质量校验模块定制开发计划
|
|
|
|
## 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. 最终结论
|
|
|
|
按当前仓库和你已经确认的需求，最合适的落地方案就是：
|
|
|
|
- 独立页级图片质量检测模块
|
|
- 只做页码级模糊预警
|
|
- 异步执行
|
|
- 不阻断主流程
|
|
- 列表页和详情页只展示“第几页疑似模糊 / 建议重拍”
|
|
|
|
这就是第一版最稳、最省、最适合推进开发的模块计划。
|