feat: add tenant-scoped rule and permission management

2026-05-21 22:03:08 +08:00
parent a2c2bf1969
commit 1f1bccf3b3
193 changed files with 64463 additions and 1771 deletions
@@ -0,0 +1,350 @@
+# 文档图片质量校验模块定制开发计划
+
+## 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. 最终结论
+
+按当前仓库和你已经确认的需求，最合适的落地方案就是：
+
+- 独立页级图片质量检测模块
+- 只做页码级模糊预警
+- 异步执行
+- 不阻断主流程
+- 列表页和详情页只展示“第几页疑似模糊 / 建议重拍”
+
+这就是第一版最稳、最省、最适合推进开发的模块计划。