文件處理管線的完整實作：從掃描件到可查詢的知識庫

階段化與中間產物

docs/
  raw/           原始檔案（唯讀，永不修改）
  pages/         每頁一張正規化影像 + 頁面 metadata
  layout/        每頁的版面區塊（座標、型別、閱讀順序）
  text/          每區塊的文字（原生抽取或 OCR）
  tables/        表格結構化結果（CSV / JSON）
  merged/        合併後的結構化文件（Markdown + metadata）
  index/         切塊與向量

每個階段讀上一階段的輸出、寫自己的輸出。這樣任一階段出問題，只需要重跑那一段之後的部分，不必從頭來過。

階段一：正規化

def normalize_page(img):
    img = fix_exif_rotation(img)
    img = deskew(img)                 # 傾斜校正，OCR 準確率影響很大
    img = to_grayscale_if_scan(img)
    img = denoise(img)
    return ensure_dpi(img, target=300)  # OCR 對 DPI 敏感

階段二：版面解析與閱讀順序

• 偵測區塊型別：標題、內文、表格、圖片、頁首、頁尾、註腳。
• 排除頁首頁尾（每頁重複的內容）。
• 決定閱讀順序——雙欄版面若順序錯誤，後續全錯。

def reading_order(blocks, page_w):
    # 簡易雙欄判定：區塊中心點分布是否明顯雙峰
    centers = [(b.x0 + b.x1) / 2 for b in blocks]
    if is_bimodal(centers, page_w):
        left  = sorted([b for b in blocks if (b.x0+b.x1)/2 < page_w/2], key=lambda b: b.y0)
        right = sorted([b for b in blocks if (b.x0+b.x1)/2 >= page_w/2], key=lambda b: b.y0)
        return left + right
    return sorted(blocks, key=lambda b: (b.y0, b.x0))

階段三：分型別處理

• 內文區塊：原生 PDF 直接取文字層；掃描件走 OCR。
• 表格區塊：用表格專用模型，輸出結構化資料，另存 CSV。
• 圖片區塊：視覺模型產生檢索用描述（含圖中所有文字標籤）。

階段四：合併與品質評分

def quality_score(page):
    return {
        'ocr_conf': mean(b.confidence for b in page.text_blocks),
        'garbled_ratio': garbled_char_ratio(page.text),   # 亂碼比例
        'empty_blocks': sum(1 for b in page.blocks if not b.text.strip()),
        'needs_review': (mean_conf < 0.75 or garbled_ratio > 0.05),
    }

品質評分讓你能把「處理得不好的頁面」自動挑出來人工檢視，而不是等使用者查不到才發現。

階段五：切塊與索引

以版面結構為單位切塊，標題路徑附在片段開頭，metadata 保留頁碼與區塊座標。座標讓你能在回答時把原文位置標示在原圖上。

可維運性設計

1. 每個檔案有處理狀態表：各階段的完成時間、耗時、品質分數、錯誤訊息。
2. 支援指定階段重跑：reprocess --doc D123 --from layout。
3. 每日產出「需人工檢視」清單。
4. 版本化：處理器版本記進 metadata，升級後可篩出需要重跑的舊資料。