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

## 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. 最终结论

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

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

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