OCR/openspec/changes/archive/2025-12-08-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 提供多種渲染模式 (HTML, cell_boxes, cells_dict, translated)

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 Singleton 模式避免重複註冊

Phase 3: 記憶體管理簡化 (已完成)

3.1 統一記憶體策略引擎 (已完成 ✓)

• 3.1.1 建立 backend/app/services/memory_policy_engine.py
• 3.1.2 定義統一的記憶體策略介面 (MemoryPolicyEngine)
• 3.1.3 合併 MemoryManager 和 MemoryGuard 邏輯 (GPUMemoryMonitor + ModelManager)
• 3.1.4 整合 Semaphore 管理 (PredictionSemaphore)
• 3.1.5 簡化配置到 7 個核心項目 (MemoryPolicyConfig)
• 3.1.6 移除未使用的類：BatchProcessor, ProgressiveLoader, PriorityOperationQueue, RecoveryManager, MemoryDumper, PrometheusMetrics
• 3.1.7 代碼量從 ~2270 行減少到 ~600 行 (73% 減少)

3.2 更新服務使用新記憶體引擎 (已完成 ✓)

• 3.2.1 更新 OCRService 使用 MemoryPolicyEngine
• 3.2.2 更新 ServicePool 使用 MemoryPolicyEngine
• 3.2.3 保留舊的 MemoryGuard 作為 fallback (向後相容)
• 3.2.4 驗證 GPU 記憶體監控正常運作

Phase 4: 前端狀態管理改進

4.1 新增 TaskStore (已完成 ✓)

• 4.1.1 建立 frontend/src/store/taskStore.ts
• 4.1.2 定義任務狀態結構（currentTaskId, recentTasks, processingState）
• 4.1.3 實現 CRUD 操作和狀態轉換（setCurrentTask, updateTaskCache, updateTaskStatus）
• 4.1.4 添加 localStorage 持久化（使用 zustand persist middleware）
• 4.1.5 更新 ProcessingPage 使用 TaskStore（startProcessing, stopProcessing）
• 4.1.6 更新 TaskDetailPage 使用 TaskStore（updateTaskCache）

4.2 合併類型定義 (已完成 ✓)

• 4.2.1 審查 api.ts 和 apiV2.ts 的差異
• 4.2.2 合併共用類型定義到 apiV2.ts（LoginRequest, User, FileInfo, FileResult, ExportRule 等）
• 4.2.3 保留 api.ts 用於 V1 特定類型（BatchStatus, ProcessRequest 等）
• 4.2.4 更新所有 import 路徑（authStore, uploadStore, ResultsTable, SettingsPage, apiV2 service）
• 4.2.5 驗證 TypeScript 編譯無錯誤 ✓

Phase 5: 測試與驗證 (Direct Track 已完成)

5.1 回歸測試 (Direct Track ✓)

• 5.1.1 使用 edit.pdf 測試 Direct Track（3 頁, 51 元素, 1 表格 12 cells）✓
• 5.1.2 使用 edit3.pdf 測試 Direct Track 表格合併（2 頁, 43 cells, 12 merged）✓
• 5.1.3 使用 edit.pdf 測試 OCR Track 圖片放回（需 GPU 環境）
• 5.1.4 使用 edit3.pdf 測試 OCR Track 圖片放回（需 GPU 環境）
• 5.1.5 驗證所有 cell_boxes 座標正確（43 valid, 0 invalid）✓

5.2 效能測試 (Direct Track ✓)

• 5.2.1 測量重構後的處理時間（edit3: 0.203s, edit: 1.281s）✓
• 5.2.2 驗證記憶體使用無明顯增加（需 GPU 環境）
• 5.2.3 驗證 GPU 使用率正常（需 GPU 環境）