OCR/openspec/changes/refactor-dual-track-architecture/tasks.md

Tasks: Refactor Dual-Track Architecture

Phase 1: 修復已知 Bug (已完成)

1.1 Direct Track 表格修復 (已完成 ✓)

• 1.1.1 修改 _process_native_table() 方法使用 table.cells 處理合併單元格
• 1.1.2 使用 PyMuPDF page.find_tables() API (已在使用中)
• 1.1.3 解析 table.cells 並正確計算 row_span/col_span
• 1.1.4 處理被合併的單元格（跳過 None 值，建立 covered grid）
• 1.1.5 驗證 edit3.pdf 返回 83 個正確的 cells ✓

1.2 OCR Track 圖片路徑修復 (已完成 ✓)

• 1.2.1 修改 ocr_to_unified_converter.py 第 604-613 行
• 1.2.2 擴展視覺元素類型判斷：IMAGE, FIGURE, CHART, DIAGRAM, LOGO, STAMP
• 1.2.3 優先使用 saved_path，fallback 到 img_path
• 1.2.4 確保 content dict 包含 saved_path, path, width, height, format
• 1.2.5 程式碼已修正 (需 OCR Track 完整測試驗證)
• 1.2.6 程式碼已修正 (需 OCR Track 完整測試驗證)

1.3 Cell boxes 座標驗證 (已完成 ✓)

• 1.3.1 在 ocr_to_unified_converter.py 添加 validate_cell_boxes() 函數
• 1.3.2 檢查 cell_boxes 是否超出頁面邊界 (0, 0, page_width, page_height)
• 1.3.3 超出範圍時使用 clamped coordinates，標記 needs_fallback
• 1.3.4 添加日誌記錄異常座標
• 1.3.5 單元測試驗證座標驗證邏輯正確 ✓

1.4 過濾極小裝飾圖片 (已完成 ✓)

• 1.4.1 在 direct_extraction_engine.py 圖片提取邏輯添加面積檢查
• 1.4.2 過濾 image_area < min_image_area (默認 200 px²) 的圖片
• 1.4.3 添加 min_image_area 配置項允許調整閾值
• 1.4.4 驗證 edit3.pdf 偵測到 3 個極小裝飾圖片 ✓

1.5 移除覆蓋圖像 (已完成 ✓)

• 1.5.1 傳遞 covering_images 到 _extract_images() 方法
• 1.5.2 使用 IoU 閾值 (0.8) 和 xref 比對判斷覆蓋圖像
• 1.5.3 從最終輸出中排除覆蓋圖像
• 1.5.4 添加 _calculate_iou() 輔助方法
• 1.5.5 驗證 edit3.pdf 偵測到 6 個黑框覆蓋圖像 ✓

Phase 2: 服務層重構

2.1 提取 ProcessingOrchestrator

• 2.1.1 建立 backend/app/services/processing_orchestrator.py
• 2.1.2 從 OCRService 提取流程編排邏輯
• 2.1.3 定義 ProcessingPipeline 介面
• 2.1.4 實現 DirectPipeline 和 OCRPipeline
• 2.1.5 更新 OCRService 使用 ProcessingOrchestrator
• 2.1.6 確保現有功能不受影響

2.2 提取 TableRenderer

• 2.2.1 建立 backend/app/services/pdf_table_renderer.py
• 2.2.2 從 PDFGeneratorService 提取 HTMLTableParser
• 2.2.3 提取表格渲染邏輯到獨立類
• 2.2.4 支援合併單元格渲染
• 2.2.5 更新 PDFGeneratorService 使用 TableRenderer

2.3 提取 FontManager

• 2.3.1 建立 backend/app/services/pdf_font_manager.py
• 2.3.2 提取字體載入和快取邏輯
• 2.3.3 提取 CJK 字體支援邏輯
• 2.3.4 實現字體 fallback 機制
• 2.3.5 更新 PDFGeneratorService 使用 FontManager

Phase 3: 記憶體管理簡化

3.1 統一記憶體策略引擎

• 3.1.1 建立 backend/app/services/memory_policy_engine.py
• 3.1.2 定義統一的記憶體策略介面
• 3.1.3 合併 MemoryManager 和 MemoryGuard 邏輯
• 3.1.4 整合 Semaphore 管理
• 3.1.5 簡化配置到 3-4 個核心項目

3.2 更新服務使用新記憶體引擎

• 3.2.1 更新 OCRService 使用 MemoryPolicyEngine
• 3.2.2 更新 ServicePool 使用 MemoryPolicyEngine
• 3.2.3 移除舊的 MemoryGuard 引用
• 3.2.4 驗證 GPU 記憶體監控正常運作

Phase 4: 前端狀態管理改進

4.1 新增 TaskStore

• 4.1.1 建立 frontend/src/store/taskStore.ts
• 4.1.2 定義任務狀態結構（currentTask, tasks, processingStatus）
• 4.1.3 實現 CRUD 操作和狀態轉換
• 4.1.4 添加 localStorage 持久化
• 4.1.5 更新 ProcessingPage 使用 TaskStore
• 4.1.6 更新 TaskDetailPage 使用 TaskStore

4.2 合併類型定義

• 4.2.1 審查 api.ts 和 apiV2.ts 的差異
• 4.2.2 合併類型定義到 apiV2.ts
• 4.2.3 移除 api.ts 中的重複定義
• 4.2.4 更新所有 import 路徑
• 4.2.5 驗證 TypeScript 編譯無錯誤

Phase 5: 測試與驗證

5.1 回歸測試

• 5.1.1 使用 edit.pdf 測試 Direct Track（確保無回歸）
• 5.1.2 使用 edit3.pdf 測試 Direct Track 表格合併
• 5.1.3 使用 edit.pdf 測試 OCR Track 圖片放回
• 5.1.4 使用 edit3.pdf 測試 OCR Track 圖片放回
• 5.1.5 驗證所有 cell_boxes 座標正確

5.2 效能測試

• 5.2.1 測量重構後的處理時間
• 5.2.2 驗證記憶體使用無明顯增加
• 5.2.3 驗證 GPU 使用率正常