解决方案

质检与交付验收方案

针对需要大批量检测 PDF 规范性、完整性并输出验收报告的场景，pdf-toolkit 提供 quality-inspection 工作流：一键启用 A4 尺寸、颜色空间、渲染异常、字体嵌入、PDF 结构、源文件完整性、签名验证等 7 项检测，不执行修复，直接生成 HTML/PDF 质检报告与 Excel 明细。

适用场景

质检中心：扫描服务中心、档案数字化外包商在交付前对客户文件做批量质量检查。
交付验收：项目结项、合同归档、审计备查前，快速定位问题文件与具体页码。
周期性巡检：对已有 PDF 库进行合规性抽检，发现版式、颜色、结构、完整性异常。

一键运行

pdf-toolkit run --workflow quality-inspection --export-excel report.xlsx

命令执行结束后，再生成可视化报告：

pdf-toolkit report --category a4 --include-page-detail --max-detail-rows 500

检测项说明

检测项	说明	输出示例
A4 尺寸	检查页面是否为标准 A4（竖版/横版），标记非 A4 页码	`non_a4_pages: [2, 5]`
颜色空间	检查是否存在非允许色彩空间（如 Lab、CMYK 异常）	逐页颜色空间明细
渲染异常	检测偏粉、偏黄、反色、灰度丢失等渲染问题	`issue_type: pink`
字体嵌入	检查未嵌入字体及所在页面	`unembedded_fonts`
PDF 结构	检查 xref、trailer、对象流等结构完整性	`error_count`, `warning_count`
源文件完整性	对比当前 PDF 与源文件的页数、大小、MD5	`has_issue: true`
签名验证	调用外部验签接口验证电子签名有效性（需配置 `api_url`）	`verified: false`

签名验证默认 api_url: ""，未配置时安全降级为 verified: false 并提示“验签接口 URL 未配置”，不会导致流程中断。

典型配置

quality-inspection 工作流已内置，默认启用全部检测项：

workflows:
  quality-inspection:
    name: quality-inspection
    description: 质检中心：规范性与完整性检测
    fixers: []
    overrides:
      a4: { enabled: true }
      colorspace: { enabled: true }
      render: { enabled: true }
      font_embedding: { enabled: true }
      pdf_structure: { enabled: true }
      source_integrity: { enabled: true }
      signature_verify:
        enabled: true
        api_url: ""   # 配置为实际验签接口地址后启用真实验证

如需调整检测范围，可复制该工作流并修改 overrides：

workflows:
  my-inspection:
    fixers: []
    overrides:
      a4: { enabled: true }
      colorspace: { enabled: true }

输出交付物

SQLite 数据库：保存每份文件的 7 项检测结果，便于后续二次分析与对接内部系统。
Excel 明细：包含每文件的检测状态、问题分类、页级明细、源文件路径等字段。
HTML 质检报告：
- 处理进度与问题分类统计条形图
- 受影响文件折叠列表（按类别）
- 逐页问题明细表（页码、问题类型、描述）
PDF 质检报告：精简版，适合打印或作为邮件附件，可控制明细行数。

核心价值

检测全面：覆盖版式、颜色、渲染、字体、结构、完整性、签名 7 个维度。
定位精准：报告精确到文件 ID 与页码，方便人工复核。
不破坏原文件：纯检测工作流，不生成修复文件，适合验收环节。
易于扩展：新增检测器只需按接口规范写入结果，无需改表。
私有化部署：数据不出域，适配内网、国产化及扫描服务中心环境。

定制扩展

按标准检测器接口新增自定义检测器，注册后会自动出现在工作流配置中。
通过数据库统计与明细接口可自定义统计口径与明细输出。
通过报告生成接口可生成指定类别的专项报告。