解決方案

質檢與交付驗收方案

質檢中心 / 交付驗收方案

針對需要大批量檢測 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 與頁碼，方便人工覆核。
不破壞原文件：純檢測工作流，不生成修復文件，適合驗收環節。
易於擴展：新增檢測器只需按接口規範寫入結果，無需改表。
私有化部署：數據不出域，適配內網、國產化及掃描服務中心環境。

定製擴展

按標準檢測器接口新增自定義檢測器，註冊後會自動出現在工作流配置中。
通過數據庫統計與明細接口可自定義統計口徑與明細輸出。
通過報告生成接口可生成指定類別的專項報告。