complete_pdf_processing_system.py

import openai
import google.generativeai as genai
import base64
import cv2
import numpy as np
from PIL import Image
import fitz
import os
import re
import time
import pandas as pd
import glob
import shutil
import uuid
import argparse
import threading
import requests  # 新增 requests 用於呼叫本地 LM Studio
from typing import Optional, List, Dict
from dotenv import load_dotenv
from ultralytics import YOLO
from concurrent.futures import ThreadPoolExecutor
from tqdm import tqdm


# 載入環境變數
load_dotenv()

class MultiPlatformIDExtractor:
    def __init__(self, api_key: str, model: str = "gpt-4o-mini", base_url: Optional[str] = None):
        """
        初始化學號提取器 - 支援 OpenAI / Google Gemini (含 Gemini 3) / 本地模型
        """
        self.model = model
        self.platform = "google" if "gemini" in model.lower() else "openai"
        self.is_gemini_3 = "gemini-3" in model.lower()
        
        # 標記是否為本地 LM Studio
        self.base_url = base_url
        self.is_lmstudio = base_url is not None
        
        if self.platform == "google":
            gemini_key = os.getenv("GEMINI_API_KEY")
            if not gemini_key:
                print("⚠️ 警告：找不到 GEMINI_API_KEY，請確認 .env 設定")
            genai.configure(api_key=gemini_key)
            self.gemini_model = genai.GenerativeModel(model)
        elif not self.is_lmstudio:
            # 只有真正的 OpenAI 才需要用官方 SDK
            self.client = openai.OpenAI(api_key=api_key or "dummy-key")

        self.is_reasoning_model = (
            (model.startswith('o') and 'mini' in model) or self.is_gemini_3 or "Lmstudio" in model.lower()
        )
        
        self.yolo_model_path = "./model/best.pt"
        try:
            self.yolo_model = YOLO(self.yolo_model_path)
        except:
            self.yolo_model = None
        
        self.prompt = self.prompt = """
你是一個精準的資料提取系統。請仔細辨識這張圖片中的「手寫學號」。
規則：
1. 尋找「Student ID」或「ID」標記後的數字
2. 學號開頭可能 1 也可能是字母 s、S，或數字 5（手寫容易混淆），後面接 6~7 位數字。
3. **請原樣回傳你看到的完整學號字串，包含開頭的 s/S/5**（例如：1123456、s1123456、S1123456、51123456）。
4. 不要自行判斷開頭是否合法，直接回傳原始辨識結果。
5. 最終結果只返回該學號字串，不要包含任何解釋文字。
6. 如果找不到學號，請回傳「NOT_FOUND」。
"""

    def encode_image_to_base64(self, image_path: str) -> str:
        with open(image_path, "rb") as image_file:
            return base64.b64encode(image_file.read()).decode('utf-8')

    # ── 底層工具方法 ──────────────────────────────────────────────────────────

    def _load_raw_image(self, image_path: str) -> np.ndarray:
        """將 PDF 第一頁或圖片檔讀入為 BGR numpy array"""
        ext = os.path.splitext(image_path)[1].lower()
        
        if ext == '.pdf':
            # 使用 PyMuPDF (fitz) 開啟 PDF，免裝 Poppler
            doc = fitz.open(image_path)
            page = doc.load_page(0) # 讀取第一頁 (index 0)
            
            # 設定解析度，對應原本的 dpi=200
            # 預設是 72 dpi，200/72 約等於 2.77 倍縮放
            zoom = 200 / 72.0
            mat = fitz.Matrix(zoom, zoom)
            pix = page.get_pixmap(matrix=mat, alpha=False)
            
            # 將圖片資料轉換為 numpy array
            img_array = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.h, pix.w, pix.n)
            doc.close()
            
            # PyMuPDF 預設提取為 RGB，OpenCV 需要 BGR
            return cv2.cvtColor(img_array, cv2.COLOR_RGB2BGR)

        # 處理一般圖片檔
        return cv2.imdecode(np.fromfile(image_path, dtype=np.uint8), cv2.IMREAD_COLOR)

    def _enhance_crop(self, crop: np.ndarray) -> str:
        """對單一裁切區域做 CLAHE 增強與縮放，儲存為唯一 temp 檔，回傳路徑"""
        import tempfile
        # 使用系統 temp 目錄，避免 Windows 對 cwd 的路徑/權限問題
        temp_path = os.path.join(tempfile.gettempdir(), f"temp_{uuid.uuid4().hex}.jpg")
        lab = cv2.cvtColor(crop, cv2.COLOR_BGR2LAB)
        l, a, b = cv2.split(lab)
        clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
        l = clahe.apply(l)
        enhanced = cv2.cvtColor(cv2.merge([l, a, b]), cv2.COLOR_LAB2BGR)
        h_e, w_e = enhanced.shape[:2]
        if max(h_e, w_e) > 1024:
            scale = 1024 / max(h_e, w_e)
            enhanced = cv2.resize(enhanced, (int(w_e * scale), int(h_e * scale)))
        cv2.imwrite(temp_path, enhanced)
        return temp_path

    def _enhance_crop_aggressive(self, crop: np.ndarray, variant: int = 0) -> str:
        """
        Phase 3 專用：提供多種不同的影像前處理策略，
        讓每次重試得到不同的輸入，突破低 temperature 的確定性瓶頸。
        variant 0 = 標準 CLAHE（同 Phase 1）
        variant 1 = 高對比二值化（Otsu）
        variant 2 = 加強銳化 + 放大
        variant 3 = 反色（適合深底淺字）
        """
        import tempfile
        temp_path = os.path.join(tempfile.gettempdir(), f"temp_p3_{uuid.uuid4().hex}.jpg")

        gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY)

        if variant == 0:
            # 標準 CLAHE（與 Phase 1 相同，作為基準）
            lab = cv2.cvtColor(crop, cv2.COLOR_BGR2LAB)
            l, a, b = cv2.split(lab)
            clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
            l = clahe.apply(l)
            result = cv2.cvtColor(cv2.merge([l, a, b]), cv2.COLOR_LAB2BGR)

        elif variant == 1:
            # Otsu 二值化 → 轉回 BGR
            _, bw = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
            result = cv2.cvtColor(bw, cv2.COLOR_GRAY2BGR)

        elif variant == 2:
            # 強銳化核 + 放大 1.5x
            kernel = np.array([[-1, -1, -1],
                                [-1,  9, -1],
                                [-1, -1, -1]])
            sharpened = cv2.filter2D(crop, -1, kernel)
            h, w = sharpened.shape[:2]
            result = cv2.resize(sharpened, (int(w * 1.5), int(h * 1.5)),
                                interpolation=cv2.INTER_CUBIC)

        elif variant == 3:
            # 反色（深底淺字的學生有時用深色筆）
            result = cv2.cvtColor(cv2.bitwise_not(gray), cv2.COLOR_GRAY2BGR)

        else:
            # fallback：直接使用原圖
            result = crop.copy()

        # 統一縮放上限
        h_r, w_r = result.shape[:2]
        if max(h_r, w_r) > 1024:
            scale = 1024 / max(h_r, w_r)
            result = cv2.resize(result, (int(w_r * scale), int(h_r * scale)))

        cv2.imwrite(temp_path, result)
        return temp_path

    def detect_all_header_regions(self, image: np.ndarray) -> List[np.ndarray]:
        """
        偵測圖片中所有 header 區域（多頁合圖時可能有多個）。
        按 y 座標由上到下排序回傳；若 YOLO 無結果則 fallback 到左上角 1/3。
        """
        fallback = [image[0:image.shape[0] // 3, 0:image.shape[1] // 2]]
        if self.yolo_model is None:
            return fallback
        try:
            results = self.yolo_model(image, verbose=False)
            header_boxes = []
            for result in results:
                for box in result.boxes:
                    if result.names[int(box.cls[0])] == 'header' and float(box.conf[0]) > 0.5:
                        x1, y1, x2, y2 = box.xyxy[0].cpu().numpy().astype(int)
                        header_boxes.append({'bbox': (x1, y1, x2, y2), 'conf': float(box.conf[0])})
            if not header_boxes:
                return fallback
            # 由上到下排列（y 座標升序），同 y 則信心度高者優先
            header_boxes.sort(key=lambda b: (b['bbox'][1], -b['conf']))
            return [image[y1:y2, x1:x2] for (x1, y1, x2, y2) in
                    [hb['bbox'] for hb in header_boxes]]
        except:
            return fallback

    def _call_llm_on_path(self, processed_path: str, max_retries: int = 2,
                          temperature: float = 0.1,
                          custom_prompt: Optional[str] = None) -> Optional[str]:
        """對單一已增強的圖片路徑呼叫 LLM，回傳辨識出的學號或 None"""
        for attempt in range(max_retries):
            base_prompt = custom_prompt if custom_prompt else self.prompt
            dynamic_prompt = base_prompt + f"\n\n[System Note: timestamp={time.time()}]"
            try:
                if self.platform == "google":
                    with Image.open(processed_path) as raw_img:
                        try:
                            config = {"thinking_level": "low"} if self.is_gemini_3 else {}
                            response = self.gemini_model.generate_content([dynamic_prompt, raw_img], generation_config=config)
                        except:
                            response = self.gemini_model.generate_content([dynamic_prompt, raw_img])
                        result = response.text.strip()

                elif self.is_lmstudio:  # 這個 flag 同時涵蓋 LM Studio 和 vLLM
                    base64_image = self.encode_image_to_base64(processed_path)
                    
                    # 動態查詢實際掛載的模型名稱,並印出到 log
                    try:
                        r = requests.get(
                            f"{self.base_url}/models",
                            timeout=15,
                            proxies={"http": None, "https": None},
                        )
                        if r.status_code == 200:
                            data = r.json().get("data", [])
                            if data:
                                actual_model = data[0].get("id") or self.model
                                max_model_len = data[0].get("max_model_len")
                                
                                # 👇 印出模型名稱到 log(僅在第一次解析時印)
                                if not getattr(self, "_logged_resolved_model", False):
                                    info = f"    🔎 {self.base_url} 模型名稱解析為:{actual_model}"
                                    if max_model_len:
                                        info += f"  (max_model_len={max_model_len})"
                                    print(info)
                                    self._logged_resolved_model = True
                            else:
                                actual_model = self.model
                        else:
                            print(f"    ⚠️ /models 端點回應 {r.status_code},fallback 使用設定的名稱: {self.model}")
                            actual_model = self.model
                    except Exception as e:
                        print(f"    ⚠️ 模型名稱解析失敗 ({type(e).__name__}: {e}),fallback 使用: {self.model}")
                        actual_model = self.model
                    
                    payload = {
                        "model": actual_model,          # ← 用動態查詢的名稱
                        "messages": [{"role": "user", "content": [
                            {"type": "text", "text": dynamic_prompt},
                            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}}
                        ]}],
                        "max_tokens": 500,              # ← OCR 任務不需要 100000，改小加速
                        "temperature": temperature,
                        "stream": False,
                        "chat_template_kwargs": {"enable_thinking": False}  # Qwen3 關閉思考
                    }
                    resp = requests.post(
                        f"{self.base_url}/chat/completions",
                        json=payload,
                        headers={"Content-Type": "application/json"},
                        timeout=120,
                        proxies={"http": None, "https": None}
                    )
                    if resp.status_code == 200:
                        data = resp.json()["choices"][0]["message"]
                        raw_result = data.get("content", "").strip()
                        # vLLM 若有開 reasoning-parser，思考會在 reasoning/reasoning_content
                        # 這裡不需要思考內容，只取 content 即可
                        result = re.sub(r'<think>.*?</think>', '', raw_result, flags=re.DOTALL).strip()
                        result = re.sub(r'<think>.*',          '', result,     flags=re.DOTALL).strip()
                    else:
                        print(f"      ✗ API 錯誤 ({resp.status_code}): {resp.text[:100]}")
                        result = ""

                else:
                    base64_image = self.encode_image_to_base64(processed_path)
                    api_params = {
                        "model": self.model,
                        "messages": [{"role": "user", "content": [
                            {"type": "text", "text": dynamic_prompt},
                            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}", "detail": "high"}}
                        ]}]
                    }
                    if self.is_reasoning_model:
                        api_params["max_completion_tokens"] = 30000
                    else:
                        api_params["max_tokens"] = 15000
                        api_params["temperature"] = temperature
                    response = self.client.chat.completions.create(**api_params)
                    result = response.choices[0].message.content.strip()

                if result and result != "NOT_FOUND":
                    cleaned = re.sub(r'[\s\-_/\\]', '', result)
                    # 接受 s/S/5 開頭（手寫混淆）或純數字，後接 6~8 位數字
                    # 例：s1123456 / S1123456 / 51123456 / 1123456
                    nums = re.findall(r'\b[sS5]?\d{6,8}\b', cleaned)
                    if nums:
                        return nums[0]

                if attempt < max_retries - 1:
                    time.sleep(1)

            except Exception as e:
                print(f"      ✗ 提取失敗 (Attempt {attempt + 1}): {e}")
                time.sleep(1)
        return None

    # ── 多頁首辨識主流程 ──────────────────────────────────────────────────────

    def extract_all_student_ids(self, image_path: str,
                                debug_save_dir: Optional[str] = None,
                                phase3_mode: bool = False) -> dict:
        """
        偵測圖片中所有 header 區域，各自送 LLM 辨識，再以多數決決定學號。

        phase3_mode=True 時：對每個 header 區域嘗試 4 種不同前處理策略，
        並使用更高 temperature（0.6）與更強的 prompt，
        避免與 Phase 1 輸出完全相同的確定性結果。

        回傳 dict：
          region_count  - 偵測到幾個 header 區域
          candidates    - 每個區域辨識出的學號（None 表示該區域辨識失敗）
          vote_counts   - 各學號得票數
          winner        - 多數決贏家（平手時為 None）
          is_tie        - 是否平手
          tied_ids      - 平手時所有同分學號（非平手時為空 list）
        """
        from collections import Counter

        # Phase 3 使用更高 temperature 與強化 prompt
        P3_TEMPERATURE = 0.6
        P3_PROMPT = self.prompt + """
【重要補充】這份試卷的學號字跡可能非常潦草或不清楚。
請仔細觀察每一個數字：
- 「1」與「7」、「4」 容易混淆
- 「0」與「6」、「8」、「9」容易混淆  
- 「3」與「8」、「5」容易混淆
- 「s/S」與「5」容易混淆
請盡量給出最可能的學號，即使不確定也請猜測，不要回傳 NOT_FOUND。
"""

        raw_image = self._load_raw_image(image_path)
        crops = self.detect_all_header_regions(raw_image)
        region_count = len(crops)

        candidates: List[Optional[str]] = []

        if not phase3_mode:
            # ── 標準模式（Phase 1 / Phase 2）──────────────────────────────────
            temp_paths: List[str] = []
            try:
                for i, crop in enumerate(crops):
                    temp_path = self._enhance_crop(crop)
                    temp_paths.append(temp_path)
                    if debug_save_dir:
                        os.makedirs(debug_save_dir, exist_ok=True)
                        shutil.copy2(temp_path,
                                     os.path.join(debug_save_dir, f"header_{i + 1}.jpg"))
                    sid = self._call_llm_on_path(temp_path)
                    candidates.append(sid)
            finally:
                for tp in temp_paths:
                    if os.path.exists(tp):
                        try: os.remove(tp)
                        except: pass
        else:
            # ── Phase 3 強化模式：每個 header 嘗試 4 種前處理，各自取結果 ────
            NUM_VARIANTS = 4
            for i, crop in enumerate(crops):
                variant_results: List[Optional[str]] = []
                for v in range(NUM_VARIANTS):
                    temp_path = self._enhance_crop_aggressive(crop, variant=v)
                    try:
                        sid = self._call_llm_on_path(
                            temp_path,
                            temperature=P3_TEMPERATURE,
                            custom_prompt=P3_PROMPT,
                        )
                        variant_results.append(sid)
                        print(f"       variant {v}: {sid or 'None'}")
                    finally:
                        if os.path.exists(temp_path):
                            try: os.remove(temp_path)
                            except: pass

                # 取 4 個 variant 中的多數決結果作為這個 header 的答案
                valid_variants = [s for s in variant_results if s is not None]
                if valid_variants:
                    from collections import Counter as _C
                    best_v = _C(valid_variants).most_common(1)[0][0]
                    candidates.append(best_v)
                    print(f"     header {i+1} variant vote: {dict(_C(valid_variants))} → {best_v}")
                else:
                    candidates.append(None)
                    print(f"     header {i+1} variant vote: 全部失敗 → None")

        # ── 多數決 ────────────────────────────────────────────────────────────
        valid = [c for c in candidates if c is not None]
        if not valid:
            return {
                'region_count': region_count, 'candidates': candidates,
                'vote_counts': {}, 'winner': None,
                'is_tie': False, 'tied_ids': []
            }

        counts = Counter(valid)
        max_votes = max(counts.values())
        top_ids = [sid for sid, cnt in counts.items() if cnt == max_votes]
        is_tie = len(top_ids) > 1

        return {
            'region_count': region_count,
            'candidates': candidates,
            'vote_counts': dict(counts),
            'winner': top_ids[0] if not is_tie else None,
            'is_tie': is_tie,
            'tied_ids': top_ids if is_tie else [],
        }

    def extract_student_id(self, image_path: str, max_retries: int = 2,
                           debug_save_path: Optional[str] = None) -> Optional[str]:
        """向下相容的單一學號介面，內部呼叫 extract_all_student_ids 取多數決贏家"""
        result = self.extract_all_student_ids(image_path)
        return result['winner'] if not result['is_tie'] else result['tied_ids'][0]

# ─── 測試模式輔助函式 ────────────────────────────────────────────────────────
def _save_test_artifacts(
    debug_save_dir: Optional[str],
    target_dir: str,
    base_name: str,
    res: dict,
):
    """
    將 YOLO 裁切的所有 header 圖片與辨識結果 txt 存入 target_dir。
    debug_save_dir 是 extract_all_student_ids 中暫存裁切圖的目錄。
    """
    os.makedirs(target_dir, exist_ok=True)

    # 1. 搬移所有裁切圖（header_1.jpg, header_2.jpg, ...）
    if debug_save_dir and os.path.isdir(debug_save_dir):
        for img_file in sorted(os.listdir(debug_save_dir)):
            if img_file.endswith('.jpg'):
                src = os.path.join(debug_save_dir, img_file)
                dst = os.path.join(target_dir, f"{base_name}_{img_file}")
                try:
                    shutil.move(src, dst)
                except Exception as e:
                    print(f"      ⚠️ 無法移動裁切圖片 {img_file}: {e}")
        # 清理暫存目錄
        try: shutil.rmtree(debug_save_dir)
        except: pass

    # 2. 寫入辨識結果 txt
    txt_path = os.path.join(target_dir, f"{base_name}_id.txt")
    candidates = res.get('candidates', [])
    vote_counts = res.get('vote_counts', {})
    region_count = res.get('region_count', len(candidates))

    try:
        with open(txt_path, 'w', encoding='utf-8') as f:
            f.write(f"原始檔案    : {base_name}\n")
            f.write(f"偵測區域數  : {region_count}\n")
            f.write(f"各區域辨識  : {candidates}\n")
            f.write(f"得票統計    : {vote_counts}\n")
            f.write("─" * 40 + "\n")
            if res.get('status') == 'success':
                f.write(f"最終學號    : {res.get('student_id')}\n")
                f.write(f"配對學生    : {res.get('student_name')}\n")
                f.write(f"CSV學號     : {res.get('csv_id')}\n")
                f.write(f"匹配類型    : {res.get('match_type')}\n")
                if res.get('tie_resolved_from'):
                    f.write(f"平手解決自  : {res.get('tie_resolved_from')}\n")
            else:
                f.write(f"配對結果    : 未配對 (狀態: {res.get('status')})\n")
    except Exception as e:
        print(f"      ⚠️ 無法寫入 txt: {e}")
# ────────────────────────────────────────────────────────────────────────────


class PDFProcessingSystem:
    def __init__(self, test_mode: bool = False):
        self.csv_file_path = None
        self.gradebook_df = None
        self.output_folder = None
        self.extractor = None
        self.extraction_results = []
        self.test_mode = test_mode
        self._dup_lock = threading.Lock()
        # key: (folder_name, sid)  value: 已放入的檔案數（從 1 開始）
        self._placed_files: Dict[tuple, int] = {}
        if test_mode:
            print("🧪 【測試模式已啟用】將儲存 YOLO 裁切圖片與辨識學號至各學生資料夾")

    def setup_extractor(self):
        models = {
            "1": ("gpt-4o-mini", "最佳性價比"), 
            "2": ("gemini-3-pro-preview", "Google 旗艦思考型"), 
            "3": ("o4-mini", "推理優化"), 
            "4": ("gpt-4o", "高階功能"), 
            "5": ("Lmstudio", "本地模型 (DGX 視覺專用)"),
            "6": ("Qwen3.6-35B-A3B", "vLLM Qwen3.6 本地推論")
        }
        print("\n=== 步驟 2.1: 設定學號提取器 ===")
        for k, v in models.items():
            print(f"{k}. {v[0]} ({v[1]})")
        choice = input(f"選擇 (1-6, 默認1): ").strip() or "1"
        selected = models.get(choice, models["1"])[0]
        
        # 決定 base_url
        if choice == "5":
            print("LM Studio 目前無法使用")
            import sys
            sys.exit(0)
        elif choice == "6":
            base_url = "http://192.168.1.175:8001/v1"
        else:
            base_url = None
        
        # === 以下是被截斷的部分,補回來 ===
        
        # 取得 API key (本地模型不需要)
        api_key = os.getenv("OPENAI_API_KEY", "dummy-key")
        
        print(f"✓ 使用模型: {selected}")
        if base_url:
            print(f"✓ Base URL: {base_url}")
        
        # 實際建立提取器並賦值給 self.extractor
        try:
            self.extractor = MultiPlatformIDExtractor(
                api_key=api_key,
                model=selected,
                base_url=base_url
            )
            print(f"✓ 學號提取器建立成功")
            return True
        except Exception as e:
            print(f"❌ 學號提取器建立失敗: {e}")
            import traceback
            traceback.print_exc()
            self.extractor = None
            return False

    def calculate_match_score(self, csv_id: str, extracted_id: str) -> tuple:
        # 1. 完全匹配
        if csv_id.lstrip('0') == extracted_id.lstrip('0'):
            return 10, "exact"
        
        # 2. 補全匹配 (AI抓到6位，前面補1可對齊)
        if len(extracted_id) == 6 and csv_id.startswith('1' + extracted_id):
            return 9, "complement"

        # 3. 缺漏字元容錯 (CSV 7位, AI只抓到 6位)
        if len(csv_id) == 7 and len(extracted_id) == 6:
            for skip_pos in range(7):
                # 嘗試拔掉 CSV 的某一位數來比對
                test_id = csv_id[:skip_pos] + csv_id[skip_pos+1:]
                if test_id == extracted_id:
                    missing_char = csv_id[skip_pos]
                    if missing_char == '0':
                        return 9, f"missing_zero_at_pos{skip_pos}"
                    else:
                        return 8, f"missing_digit_{missing_char}_at_pos{skip_pos}"
            
            # 3.5 對齊匹配 (容許錯位)
            best_similarity = 0
            best_skip_pos = -1
            for skip_pos in range(7):
                test_id = csv_id[:skip_pos] + csv_id[skip_pos+1:]
                similarity = sum(c1 == c2 for c1, c2 in zip(test_id, extracted_id))
                if similarity > best_similarity:
                    best_similarity = similarity
                    best_skip_pos = skip_pos
            
            # 若相似度 >= 5 (逾70%)，認為匹配成功
            if best_similarity >= 5:
                return best_similarity + 1, f"aligned_match_skip_pos{best_skip_pos}_sim{best_similarity}"
        
        # 4. 多餘字元容錯 (CSV 7位, AI抓到 8位)
        if len(csv_id) == 7 and len(extracted_id) == 8:
            for skip_pos in range(8):
                # 嘗試忽略 AI 多抓的那個字
                test_id = extracted_id[:skip_pos] + extracted_id[skip_pos+1:]
                if test_id == csv_id:
                    extra_char = extracted_id[skip_pos]
                    if extra_char in '01':
                        return 7, f"extra_digit_{extra_char}_at_pos{skip_pos}"
                    else:
                        return 6, f"extra_digit_{extra_char}_at_pos{skip_pos}"

        # 5. 模糊匹配兜底方案
        if len(csv_id) == 7 and len(extracted_id) >= 6:
            if len(extracted_id) == 7:
                similarity = sum(c1 == c2 for c1, c2 in zip(csv_id, extracted_id))
            elif len(extracted_id) == 6:
                similarity = sum(c1 == c2 for c1, c2 in zip(csv_id, extracted_id.zfill(7)))
            else:  # len(extracted_id) == 8
                similarity = sum(c1 == c2 for c1, c2 in zip(csv_id, extracted_id))
            
            if similarity >= 5:
                return similarity, f"fuzzy_{similarity}"
        
        # 皆不符合
        return 0, "none"

    def find_student_by_id(self, student_id: str):
        # 正規化：去除 s/S/5 開頭（手寫或 LLM 誤判產生的前綴）
        normalized_id = re.sub(r'^[sS5]', '', student_id)
        if normalized_id != student_id:
            print(f"      → 前綴正規化: '{student_id}' → '{normalized_id}'")
        student_id = normalized_id

        candidates = []
        
        for index, row in self.gradebook_df.iterrows():
            if pd.isna(row.get('Identifier', '')):
                continue
            
            # 檢查所有可能包含學號的欄位
            fields_to_check = [
                str(row.get('Identifier', '')).strip(),
                str(row.get('Username', '')).strip(),
                str(row.get('Full name', '')).strip()
            ]
            
            for field_value in fields_to_check:
                extracted_id = None
                
                # 嘗試匹配 s1xxxxxx 或 S1xxxxxx 格式
                s_match = re.search(r'[sS](\d{7})', field_value)
                if s_match:
                    extracted_id = s_match.group(1)
                else:
                    number_match = re.search(r'(\d{7})', field_value)
                    if number_match:
                        extracted_id = number_match.group(1)
                
                if extracted_id:
                    score, m_type = self.calculate_match_score(extracted_id, student_id)
                    if score >= 5:
                        name = str(row['Full name']).strip()
                        id_str = str(row['Identifier']).strip()
                        p_match = re.search(r'Participant\s+(\d+)', id_str)
                        temp_num = p_match.group(1) if p_match else str(index + 1).zfill(3)
                        folder = f"{name}_{temp_num}_assignsubmission_file"
                        
                        candidates.append({
                            'full_name': name, 
                            'folder_name': folder, 
                            'csv_id': extracted_id, 
                            'temp_num': temp_num, 
                            'score': score, 
                            'type': m_type
                        })
                        break # 找到匹配就換下一個學生
        
        if not candidates:
            return None, None, None, None, "none"
        
        # 按匹配分數排序（分數越高越好）
        candidates.sort(key=lambda x: x['score'], reverse=True)
        
        best_score = candidates[0]['score']
        best_candidates = [c for c in candidates if c['score'] == best_score]
        
        # 取最高分，若有多個同分候選，標記為 multiple_candidates 供後續分析，但自動流程暫選第一個
        best = best_candidates[0]
        if len(best_candidates) > 1:
            match_type = f"multiple_candidates_{len(best_candidates)}"
        else:
            match_type = best['type']
            
        return best['full_name'], best['folder_name'], best['csv_id'], best['temp_num'], match_type

    def process_single_file(self, f_path):
        """並行處理中的單一檔案任務"""
        filename = os.path.basename(f_path)
        base_name = os.path.splitext(filename)[0].strip()  # strip 去除 Windows 尾部空格問題

        # 測試模式：為這份檔案建立唯一暫存 debug 目錄
        debug_save_dir = None
        if self.test_mode:
            debug_save_dir = os.path.join(
                os.path.dirname(f_path),
                f"_dbg_{uuid.uuid4().hex}_{base_name}"
            )

        try:
            # ── Step 1：多區域辨識 + 多數決 ──────────────────────────────────
            vote_result = self.extractor.extract_all_student_ids(
                f_path, debug_save_dir=debug_save_dir
            )
            region_count = vote_result['region_count']
            candidates   = vote_result['candidates']
            vote_counts  = vote_result['vote_counts']

            res = {
                'original_filename': filename,
                'student_id': None,
                'status': 'failed',
                'region_count': region_count,
                'candidates': candidates,
                'vote_counts': vote_counts,
            }

            target_dir = None

            # ── Step 2a：多數決有明確贏家 ─────────────────────────────────────
            if vote_result['winner']:
                sid = vote_result['winner']
                res['student_id'] = sid
                name, folder, csv_id, temp_num, m_type = self.find_student_by_id(sid)
                if name:
                    target_dir = os.path.join(self.output_folder, folder)
                    res.update(self._place_file(f_path, target_dir, sid, name, csv_id, m_type))

            # ── Step 2b：平手 → 各候選各自跑 fuzzy，取最高分 ─────────────────
            elif vote_result['is_tie']:
                best_score, best_match = -1, None
                for tied_sid in vote_result['tied_ids']:
                    name, folder, csv_id, temp_num, m_type = self.find_student_by_id(tied_sid)
                    if name is None:
                        continue
                    # 用 match_type 對應一個數值分數來比較
                    numeric_score = self._match_type_to_score(m_type)
                    if numeric_score > best_score:
                        best_score  = numeric_score
                        best_match  = (tied_sid, name, folder, csv_id, m_type)

                if best_match:
                    sid, name, folder, csv_id, m_type = best_match
                    res['student_id'] = sid
                    res['tie_resolved_from'] = vote_result['tied_ids']
                    target_dir = os.path.join(self.output_folder, folder)
                    res.update(self._place_file(f_path, target_dir, sid, name, csv_id,
                                                f"tie_resolved({m_type})"))

            # ── Step 3：失敗檔案移至 _unmatched/ ────────────────────────────
            if res.get('status') != 'success':
                unmatched_dir = os.path.join(self.output_folder, "_unmatched")
                os.makedirs(unmatched_dir, exist_ok=True)
                dst = os.path.join(unmatched_dir, filename)
                try:
                    shutil.copy2(f_path, dst)
                    res['moved_to_unmatched'] = True
                except Exception as e:
                    print(f"      ⚠️ 無法移至 _unmatched/：{e}")

            # ── Step 4：測試模式寫入 artifacts ───────────────────────────────
            if self.test_mode:
                if res.get('status') == 'success' and target_dir:
                    _save_test_artifacts(debug_save_dir, target_dir, base_name, res)
                else:
                    unmatched_dir = os.path.join(self.output_folder, "_unmatched")
                    os.makedirs(unmatched_dir, exist_ok=True)
                    _save_test_artifacts(debug_save_dir, unmatched_dir, base_name, res)

            return res

        except Exception as e:
            # 清理暫存 debug 目錄
            if debug_save_dir and os.path.isdir(debug_save_dir):
                try: shutil.rmtree(debug_save_dir)
                except: pass
            return {'original_filename': filename, 'status': f'error: {str(e)}'}

    # ── 輔助方法 ──────────────────────────────────────────────────────────────

    def _place_file(self, src_path, target_dir, sid, name, csv_id, m_type) -> dict:
        """Thread-safe 序號命名後 copy 進 target_dir，回傳 res 更新 dict"""
        ext = os.path.splitext(src_path)[1]
        dup_key = (target_dir, sid)
        with self._dup_lock:
            count = self._placed_files.get(dup_key, 0) + 1
            self._placed_files[dup_key] = count
            if count == 1:
                dst_name = f"{sid}{ext}"
            elif count == 2:
                old = os.path.join(target_dir, f"{sid}{ext}")
                if os.path.exists(old):
                    os.rename(old, os.path.join(target_dir, f"{sid}_1{ext}"))
                dst_name = f"{sid}_2{ext}"
            else:
                dst_name = f"{sid}_{count}{ext}"
        shutil.copy2(src_path, os.path.join(target_dir, dst_name))
        return {
            'status': 'success',
            'student_name': name,
            'csv_id': csv_id,
            'match_type': m_type,
            'saved_as': dst_name,
            'is_duplicate': count > 1,
            'dup_index': count,
        }

    @staticmethod
    def _match_type_to_score(m_type: str) -> int:
        """將 match_type 字串轉為可比較的數值分數（越高越好）"""
        if m_type == 'exact':                          return 10
        if m_type == 'complement':                     return 9
        if 'missing_zero' in m_type:                   return 9
        if 'missing_digit' in m_type:                  return 8
        if 'aligned_match' in m_type:                  return 7
        if 'extra_digit_0' in m_type or 'extra_digit_1' in m_type: return 7
        if 'extra_digit' in m_type:                    return 6
        if 'fuzzy' in m_type:
            try: return int(m_type.split('_')[1])
            except: return 5
        if 'multiple_candidates' in m_type:            return 4
        return 0

    def _row_to_folder_key_and_csv_id(self, row, index: int) -> tuple:
        """
        從 gradebook_df 的單一 row 解析出 (folder_key, csv_id)。
        Moodle 版（預設）使用 Identifier / Username / Full name 欄位。
        獨立考試版（ExamPDFProcessingSystem）覆寫此方法改用「學號」「姓名」。
        回傳 (folder_key: str, csv_id: str | None)
        """
        id_str = str(row.get('Identifier', '')).strip()
        p_match = re.search(r'Participant\s+(\d+)', id_str)
        num = p_match.group(1) if p_match else str(index + 1).zfill(3)
        folder_key = f"{str(row.get('Full name', '')).strip()}_{num}_assignsubmission_file"

        csv_id = None
        for field_value in [id_str, str(row.get('Username', '')).strip()]:
            s_match = re.search(r'[sS](\d{7})', field_value)
            csv_id = s_match.group(1) if s_match else None
            if not csv_id:
                nm = re.search(r'(\d{7})', field_value)
                csv_id = nm.group(1) if nm else None
            if csv_id:
                break

        return folder_key, csv_id

    def resolve_duplicate_folders(self) -> List[dict]:
        """
        第二階段：掃描所有學生資料夾，找出含兩個以上作業檔案的資料夾
        （代表兩份試卷因匹配機制被分到同一位學生）。

        處理邏輯：
          1. 對衝突資料夾內的每個檔案重新辨識學號、重新計算匹配分數
          2. 最高分者保留在原資料夾
          3. 低分者在「目前仍為空的學生資料夾」中從 CSV 全表重新匹配
          4. 若無空資料夾可配，移至 _unmatched/

        回傳：resolution_log，每筆代表一個被移動的檔案
        """
        print("\n" + "=" * 60)
        print("🔍 第二階段：衝突資料夾偵測與重新分配")
        print("=" * 60)

        # ── 輔助：列出資料夾內的「學生作業檔案」（排除 debug 輔助檔） ──────────
        def list_student_files(fp: str) -> List[str]:
            if not os.path.isdir(fp):
                return []
            return [
                f for f in os.listdir(fp)
                if os.path.isfile(os.path.join(fp, f))
                and not f.endswith(('_header.jpg', '_id.txt'))
                and not f.startswith('.')
            ]

        # ── 掃描所有非系統資料夾 ──────────────────────────────────────────────
        conflict_folders: Dict[str, List[str]] = {}  # folder_path -> [檔名列表]
        normal_folders:   List[str]            = []  # 非衝突資料夾路徑

        for fn in sorted(os.listdir(self.output_folder)):
            fp = os.path.join(self.output_folder, fn)
            if not os.path.isdir(fp) or fn.startswith('_'):
                continue
            files = list_student_files(fp)
            if len(files) >= 2:
                conflict_folders[fp] = files
            else:
                normal_folders.append(fp)

        if not conflict_folders:
            print("✅ 所有資料夾均為單一檔案，無需第二階段處理。")
            return []

        print(f"⚠️  發現 {len(conflict_folders)} 個衝突資料夾，開始處理…")
        resolution_log: List[dict] = []

        # ── 輔助：取得目前仍為空的資料夾路徑列表（每次移動後需重新計算） ──────
        def get_empty_folder_paths() -> List[str]:
            return [fp for fp in normal_folders if len(list_student_files(fp)) == 0]

        # ── 輔助：只在指定可用資料夾中尋找最佳 CSV 匹配 ────────────────────────
        def find_best_in_allowed(sid: str, allowed_fps: List[str]):
            """
            給定辨識出的學號 sid，只在 allowed_fps（空資料夾）中搜尋最佳匹配。
            回傳 (folder_path, folder_name, csv_id, score, match_type) 或 None。
            """
            if not allowed_fps:
                return None
            norm_sid = re.sub(r'^[sS5]', '', sid)
            allowed_names = {os.path.basename(fp) for fp in allowed_fps}

            best = None
            best_score = 0

            for index, row in self.gradebook_df.iterrows():
                folder_key, csv_id = self._row_to_folder_key_and_csv_id(row, index)
                if not csv_id or folder_key not in allowed_names:
                    continue
                score, m_type = self.calculate_match_score(csv_id, norm_sid)
                if score >= 5 and score > best_score:
                    best_score = score
                    best = (
                        os.path.join(self.output_folder, folder_key),
                        folder_key, csv_id, score, m_type,
                    )

            return best  # None 表示空資料夾中無任何匹配

        # ── 逐一處理衝突資料夾 ───────────────────────────────────────────────
        for folder_path, file_list in conflict_folders.items():
            folder_name = os.path.basename(folder_path)
            print(f"\n  📂 {folder_name}")
            print(f"     內含 {len(file_list)} 個檔案：{file_list}")

            # ① 重新辨識各檔案的學號與匹配分數
            file_scores: List[dict] = []
            for fname in file_list:
                fpath = os.path.join(folder_path, fname)
                print(f"     🔄 重新辨識：{fname}")
                try:
                    vote_result = self.extractor.extract_all_student_ids(fpath)
                    sid = vote_result['winner']
                    if not sid and vote_result['is_tie'] and vote_result['tied_ids']:
                        sid = vote_result['tied_ids'][0]

                    match_score, match_type = 0, 'none'
                    if sid:
                        norm_sid = re.sub(r'^[sS5]', '', sid)
                        _, _, csv_id_found, _, _ = self.find_student_by_id(sid)
                        if csv_id_found:
                            match_score, match_type = self.calculate_match_score(
                                csv_id_found, norm_sid
                            )

                    file_scores.append({
                        'fname': fname, 'fpath': fpath,
                        'sid': sid, 'score': match_score, 'match_type': match_type,
                    })
                except Exception as e:
                    print(f"     ⚠️  {fname} 辨識失敗：{e}")
                    file_scores.append({
                        'fname': fname, 'fpath': fpath,
                        'sid': None, 'score': -1, 'match_type': 'error',
                    })

            # ② 依分數排序：最高分留下，其餘移出
            file_scores.sort(key=lambda x: x['score'], reverse=True)
            winner = file_scores[0]
            losers  = file_scores[1:]

            print(f"     🏆 保留高分：{winner['fname']}"
                  f"  (score={winner['score']}, type={winner['match_type']})")

            for loser in losers:
                print(f"     ↩️  移出低分：{loser['fname']}"
                      f"  (score={loser['score']}, type={loser['match_type']})")

                empty_fps   = get_empty_folder_paths()
                best_match  = (
                    find_best_in_allowed(loser['sid'], empty_fps)
                    if loser['sid'] else None
                )

                if best_match:
                    dst_fp, dst_fn, csv_id, sc, mt = best_match
                    ext       = os.path.splitext(loser['fname'])[1]
                    sid_clean = re.sub(r'^[sS5]', '', loser['sid'])
                    dst_file  = os.path.join(dst_fp, f"{sid_clean}{ext}")
                    shutil.move(loser['fpath'], dst_file)
                    print(f"        ✅ 重新分配 → {dst_fn}  (score={sc}, type={mt})")
                    resolution_log.append({
                        'fname':       loser['fname'],
                        'from_folder': folder_name,
                        'to_folder':   dst_fn,
                        'sid':         loser['sid'],
                        'score':       sc,
                        'match_type':  mt,
                        'result':      'reassigned',
                    })
                else:
                    reason = '學號辨識失敗' if not loser['sid'] else '無空資料夾可匹配'
                    unmatched_p2 = os.path.join(self.output_folder, "_unmatched")
                    os.makedirs(unmatched_p2, exist_ok=True)
                    dst_file = os.path.join(unmatched_p2, loser['fname'])
                    shutil.move(loser['fpath'], dst_file)
                    print(f"        ⚠️  {reason} → _unmatched/")
                    resolution_log.append({
                        'fname':       loser['fname'],
                        'from_folder': folder_name,
                        'to_folder':   '_unmatched',
                        'sid':         loser['sid'],
                        'result':      'no_match',
                        'reason':      reason,
                    })

        return resolution_log

    def resolve_unmatched_phase3(self) -> List[dict]:
        """
        第三階段（選用）：寬鬆重匹配
        對象：_unmatched/ 中的所有檔案  ×  仍為空的學生資料夾
        門檻：score >= 1（能放就放，因為這些樣本學號幾乎確定寫得很亂）
        只能配進空資料夾，不會搶走已有檔案的資料夾。
        結果印出後進入人工暫停點。

        回傳：resolution_log，格式同 resolve_duplicate_folders
        """
        print("\n" + "=" * 60)
        print("🔓 第三階段：寬鬆重匹配（_unmatched/ → 空資料夾）")
        print("=" * 60)

        unmatched_dir = os.path.join(self.output_folder, "_unmatched")
        if not os.path.isdir(unmatched_dir):
            print("  ℹ️  _unmatched/ 資料夾不存在，無需執行。")
            return []

        # ── 收集 _unmatched/ 裡的所有作業檔案 ──────────────────────────────
        candidate_files = [
            f for f in os.listdir(unmatched_dir)
            if os.path.isfile(os.path.join(unmatched_dir, f))
            and not f.startswith('.')
            and not f.endswith(('_header.jpg', '_id.txt'))
        ]

        if not candidate_files:
            print("  ℹ️  _unmatched/ 資料夾中沒有待處理的檔案。")
            return []

        print(f"  📄 待重匹配檔案：{len(candidate_files)} 個")

        # ── 收集目前仍為空的學生資料夾 ───────────────────────────────────────
        def list_student_files(fp: str) -> List[str]:
            return [
                f for f in os.listdir(fp)
                if os.path.isfile(os.path.join(fp, f))
                and not f.endswith(('_header.jpg', '_id.txt'))
                and not f.startswith('.')
            ] if os.path.isdir(fp) else []

        empty_folders: List[str] = []
        for fn in sorted(os.listdir(self.output_folder)):
            fp = os.path.join(self.output_folder, fn)
            if os.path.isdir(fp) and not fn.startswith('_') and len(list_student_files(fp)) == 0:
                empty_folders.append(fp)

        print(f"  📂 尚未分配的空資料夾：{len(empty_folders)} 個")

        if not empty_folders:
            print("  ℹ️  所有學生資料夾均已有檔案，無空位可配。")
            return []

        # ── 寬鬆版匹配：只搜尋空資料夾，門檻 >= 1 ─────────────────────────
        allowed_names = {os.path.basename(fp) for fp in empty_folders}

        def find_loose_match(sid: Optional[str]):
            """在空資料夾中以最寬鬆條件（score >= 1）找最佳匹配"""
            if not sid:
                return None
            norm_sid = re.sub(r'^[sS5]', '', sid)
            best, best_score = None, 0

            for index, row in self.gradebook_df.iterrows():
                folder_key, csv_id = self._row_to_folder_key_and_csv_id(row, index)
                if not csv_id or folder_key not in allowed_names:
                    continue
                score, m_type = self.calculate_match_score(csv_id, norm_sid)
                if score >= 1 and score > best_score:
                    best_score = score
                    best = (
                        os.path.join(self.output_folder, folder_key),
                        folder_key, csv_id, score, m_type,
                    )

            return best

        # ── 逐一處理 ────────────────────────────────────────────────────────
        resolution_log: List[dict] = []

        for fname in candidate_files:
            fpath = os.path.join(unmatched_dir, fname)
            print(f"\n  🔄 重新辨識：{fname}")

            try:
                vote_result = self.extractor.extract_all_student_ids(fpath, phase3_mode=True)
                sid = vote_result['winner']
                if not sid and vote_result['is_tie'] and vote_result['tied_ids']:
                    sid = vote_result['tied_ids'][0]
                print(f"     辨識學號：{sid or '無法辨識'}")
            except Exception as e:
                print(f"     ⚠️  辨識失敗：{e}")
                sid = None

            best = find_loose_match(sid)

            if best:
                dst_fp, dst_fn, csv_id, sc, mt = best
                ext      = os.path.splitext(fname)[1]
                sid_clean = re.sub(r'^[sS5]', '', sid) if sid else 'unknown'
                dst_file  = os.path.join(dst_fp, f"{sid_clean}{ext}")
                try:
                    shutil.move(fpath, dst_file)
                    # 配對成功後，該資料夾從空資料夾清單移除
                    if dst_fp in empty_folders:
                        empty_folders.remove(dst_fp)
                    allowed_names.discard(dst_fn)
                    print(f"     ✅ 寬鬆配對成功 → {dst_fn}  (score={sc}, type={mt})")
                    resolution_log.append({
                        'fname': fname, 'sid': sid,
                        'to_folder': dst_fn, 'csv_id': csv_id,
                        'score': sc, 'match_type': mt, 'result': 'reassigned',
                    })
                except Exception as e:
                    print(f"     ⚠️  移動失敗：{e}")
                    resolution_log.append({
                        'fname': fname, 'sid': sid,
                        'result': 'move_error', 'reason': str(e),
                    })
            else:
                reason = '學號辨識失敗' if not sid else '無任何空資料夾可匹配（score 全為 0）'
                print(f"     ❌ 無法配對：{reason}")
                resolution_log.append({
                    'fname': fname, 'sid': sid,
                    'result': 'no_match', 'reason': reason,
                })

        # ── 印出摘要 ─────────────────────────────────────────────────────────
        print("\n" + "=" * 60)
        print("📋 第三階段結果摘要")
        print("=" * 60)
        ok  = [r for r in resolution_log if r['result'] == 'reassigned']
        bad = [r for r in resolution_log if r['result'] != 'reassigned']
        print(f"  ✅ 成功寬鬆配對：{len(ok)} 個")
        for r in ok:
            print(f"     • {r['fname']}  →  {r['to_folder']}  (score={r['score']}, type={r['match_type']})")
        if bad:
            print(f"  ❌ 仍無法配對（留在 _unmatched/）：{len(bad)} 個")
            for r in bad:
                print(f"     • {r['fname']}  原因：{r.get('reason','未知')}  辨識學號：{r.get('sid') or '無'}")

        # ── 人工暫停點 ───────────────────────────────────────────────────────
        remaining_empty = [
            os.path.basename(fp) for fp in empty_folders
        ]
        if remaining_empty:
            print(f"\n  📭 仍為空的學生資料夾（{len(remaining_empty)} 個）：")
            for fn in remaining_empty:
                print(f"     • {fn}")

        print("\n" + "⚠️ " * 20)
        print("Phase 3 完成，請手動確認上方結果後按 Enter 繼續後續流程...")
        print("（如需再次調整，請直接修改資料夾內容，然後按 Enter）")
        print("⚠️ " * 20)
        try:
            input("\n🔄 按 Enter 繼續，或 Ctrl+C 中止：")
            print("✅ 繼續執行後續流程…")
        except KeyboardInterrupt:
            print("\n❌ 使用者中止流程")
            raise

        return resolution_log

    def process_files(self, workers=2):  # 預設降為 2，保護本地 GPU 資源
        files = glob.glob(os.path.join("Extract_PDF", "*.*"))
        files = [f for f in files if f.lower().endswith(('.pdf', '.png', '.jpg', '.jpeg'))]
        if not files: return False
        
        print(f"\n🚀 啟動 Agent 並行處理 (線程數: {workers})")
        with ThreadPoolExecutor(max_workers=workers) as executor:
            # 使用 tqdm 顯示即時進度
            results = list(tqdm(executor.map(self.process_single_file, sorted(files)), total=len(files), desc="辨識進度", unit="file"))
        self.extraction_results = results
        return True

    def run(self):
        print("=== PDF與圖片處理系統 (Agent 並行版) ===\n")
        csv_files = glob.glob("*.csv")
        if not csv_files: 
            print("錯誤: 找不到 CSV")
            return False
            
        self.csv_file_path = csv_files[0]
        self.gradebook_df = pd.read_csv(self.csv_file_path)
        self.output_folder = os.path.splitext(os.path.basename(self.csv_file_path))[0]
        if not os.path.exists(self.output_folder): os.makedirs(self.output_folder)
        
        # 建立學生資料夾，同時建立反向映射 folder_name → df index（供第二階段使用）
        self._folder_to_row: Dict[str, int] = {}
        for idx, row in self.gradebook_df.iterrows():
            if pd.isna(row['Full name']): continue
            id_str = str(row['Identifier']).strip()
            p_match = re.search(r'Participant\s+(\d+)', id_str)
            num = p_match.group(1) if p_match else str(idx + 1).zfill(3)
            folder_name_key = f"{str(row['Full name']).strip()}_{num}_assignsubmission_file"
            f_path = os.path.join(self.output_folder, folder_name_key)
            if not os.path.exists(f_path): os.makedirs(f_path)
            self._folder_to_row[folder_name_key] = idx  # 反向映射

        self.setup_extractor()
        # 明確傳入 workers=2
        if self.process_files(workers=2):
            print("\n✓ 檔案處理完成！")
            success_count = sum(1 for r in self.extraction_results if r.get('status') == 'success')
            multi_region  = [r for r in self.extraction_results if r.get('region_count', 1) > 1]
            tie_resolved  = [r for r in self.extraction_results if r.get('tie_resolved_from')]
            duplicates    = [r for r in self.extraction_results if r.get('is_duplicate')]
            warnings      = [r for r in self.extraction_results
                             if r.get('status') == 'success'
                             and r.get('match_type', '').replace('tie_resolved(', '').rstrip(')') != 'exact'
                             and not r.get('is_duplicate')]
            failures      = [r for r in self.extraction_results if r.get('status') != 'success']

            print(f"📊 總結：成功分配 {success_count} / {len(self.extraction_results)} 個檔案")
            if multi_region:
                print(f"   🔍 多頁首偵測：{len(multi_region)} 個檔案含多個 header 區域")
            if tie_resolved:
                print(f"   ⚖️  平手解決：{len(tie_resolved)} 個檔案經 fuzzy 最高分仲裁")
            
            # ── 第二階段：解決衝突資料夾（先跑，結果才能併入人工審查區塊） ──────
            phase2_log   = self.resolve_duplicate_folders()
            p2_reassigned = [r for r in phase2_log if r['result'] == 'reassigned']
            p2_no_match   = [r for r in phase2_log if r['result'] == 'no_match']

            # 印第二階段自動重新分配的成功摘要（不需人工介入的部分）
            if p2_reassigned:
                print("\n" + "=" * 60)
                print("📋 第二階段：衝突自動解決摘要")
                print("=" * 60)
                print(f"  ✅ 成功重新分配（{len(p2_reassigned)} 個）：")
                for r in p2_reassigned:
                    print(f"     • {r['fname']}")
                    print(f"       來自: {r['from_folder']}")
                    print(f"       移至: {r['to_folder']}  (score={r['score']}, type={r['match_type']})")
                print("=" * 60)

            # --- 統一人工審查區塊（含第二階段未能匹配的項目） ---
            if duplicates or tie_resolved or warnings or failures or p2_no_match:
                print("\n" + "="*50)
                print("⚠️ 以下檔案需要【人工確認與校正】")
                print("="*50)

                if duplicates:
                    from collections import defaultdict
                    dup_groups: dict = defaultdict(list)
                    for d in duplicates:
                        dup_groups[d.get('student_id')].append(d)
                    first_files = {r.get('student_id'): r for r in self.extraction_results
                                   if r.get('status') == 'success' and r.get('dup_index') == 1
                                   and r.get('student_id') in dup_groups}
                    print(f"\n【重複頁首】(同一學號出現多張，已自動加序號保留，請確認是否為同一位學生):")
                    for sid, dup_list in dup_groups.items():
                        student_name = dup_list[0].get('student_name')
                        print(f"  • 學號: {sid}  學生: {student_name}")
                        if sid in first_files:
                            f1 = first_files[sid]
                            print(f"    - [{f1.get('dup_index')}] {f1.get('original_filename')}  →  {f1.get('saved_as')}")
                        for d in dup_list:
                            print(f"    - [{d.get('dup_index')}] {d.get('original_filename')}  →  {d.get('saved_as')}")

                if tie_resolved:
                    print(f"\n【平手仲裁】(多頁首辨識結果票數相同，已取 fuzzy 最高分，建議人工複核):")
                    for r in tie_resolved:
                        print(f"  • 檔名: {r.get('original_filename')}")
                        print(f"    - 候選學號: {r.get('tie_resolved_from')}  →  仲裁結果: {r.get('student_id')} ({r.get('student_name')})")
                        print(f"    - 得票分布: {r.get('vote_counts')}")

                if warnings:
                    print("\n【模糊/非完美匹配】 (請至對應資料夾確認是否分配正確):")
                    for w in warnings:
                        region_info = f" | 偵測 {w.get('region_count')} 個區域" if w.get('region_count', 1) > 1 else ""
                        print(f"  • 檔名: {w.get('original_filename')}{region_info}")
                        print(f"    - AI提取學號: {w.get('student_id')} -> 配對給: {w.get('student_name')} (CSV學號: {w.get('csv_id')})")
                        print(f"    - 匹配類型: {w.get('match_type')}")

                if failures:
                    print("\n【處理失敗 / 找不到學生】 (已移至 _unmatched/，需手動放入正確資料夾):")
                    for f in failures:
                        print(f"  • 檔名: {f.get('original_filename')}")
                        print(f"    - 各區域辨識: {f.get('candidates') or '無(提取失敗)'}")
                        print(f"    - 狀態: {f.get('status')}")

                if p2_no_match:
                    print(f"\n【第二階段衝突未解決】(已移至 _unmatched/，需手動放入正確資料夾):")
                    for r in p2_no_match:
                        print(f"  • 檔名: {r['fname']}")
                        print(f"    - 原資料夾: {r['from_folder']}")
                        print(f"    - 辨識學號: {r.get('sid') or '無法辨識'}")
                        print(f"    - 原因: {r.get('reason', '未知')}")

                print("="*50 + "\n")

            return True
            
        return False

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="PDF 與圖片學號辨識處理系統")
    parser.add_argument(
        "--test",
        action="store_true",
        help="測試模式：將 YOLO 裁切的 header 圖片與 AI 辨識學號存入各學生資料夾（副檔名 _header.jpg / _id.txt）"
    )
    args = parser.parse_args()
    PDFProcessingSystem(test_mode=args.test).run()