3.1 KiB
3.1 KiB
Change: Refactor Dual-Track Architecture
Why
目前雙軌制 OCR 系統存在多個已知問題和架構債務：
- Direct Track 表格問題:
_detect_tables_by_position()無法識別合併單元格，導致 edit3.pdf 產生 204 個錯誤拆分的 cells（應為 83 個） - OCR Track 圖片路徑丟失: CHART/DIAGRAM 等視覺元素的
saved_path在轉換時丟失，導致圖片未放回 PDF - OCR Track cell_boxes 座標錯亂: PP-StructureV3 返回的 cell_boxes 超出頁面邊界
- 服務層過度複雜: OCRService (2,326 行) 承擔過多職責，難以維護和測試
- PDF 生成器過於龐大: PDFGeneratorService (4,644 行) 是單體服務，難以擴展
What Changes
Phase 1: 修復已知 Bug（優先級：最高）
- Direct Track 表格修復: 改用 PyMuPDF
find_tables()API 取代_detect_tables_by_position() - OCR Track 圖片路徑修復: 擴展
_convert_pp3_element處理所有視覺元素類型 (IMAGE, FIGURE, CHART, DIAGRAM, LOGO, STAMP) - Cell boxes 座標驗證: 添加邊界檢查，超出範圍時使用 CV 線檢測 fallback
- 過濾極小裝飾圖片: 過濾 < 200 px² 的圖片
- 移除覆蓋圖像: 在渲染階段過濾與 covering_images 重疊的圖片
Phase 2: 服務層重構（優先級：高）
- 拆分 OCRService: 提取獨立的
ProcessingOrchestrator負責流程編排 - 建立 Pipeline 模式: 使用組合模式取代目前的聚合模式
- 提取 TableRenderer: 從 PDFGeneratorService 提取表格渲染邏輯
- 提取 FontManager: 從 PDFGeneratorService 提取字體管理邏輯
Phase 3: 記憶體管理簡化（優先級：中）
- 統一記憶體策略: 合併 MemoryManager、MemoryGuard、各類 Semaphore 為單一策略引擎
- 簡化配置: 減少 8+ 個記憶體相關配置項到核心 3-4 項
Phase 4: 前端狀態管理改進（優先級：中）
- 新增 TaskStore: 使用 Zustand 管理任務狀態，取代分散的 useState
- 合併類型定義: 統一 api.ts 和 apiV2.ts 為單一類型定義檔案
Impact
- Affected specs:
document-processing - Affected code:
backend/app/services/direct_extraction_engine.py(表格檢測)backend/app/services/ocr_to_unified_converter.py(元素轉換)backend/app/services/ocr_service.py(服務編排)backend/app/services/pdf_generator_service.py(PDF 生成)backend/app/services/memory_manager.py(記憶體管理)frontend/src/store/(狀態管理)frontend/src/types/(類型定義)
Risk Assessment
| 風險 | 嚴重性 | 緩解措施 |
|---|---|---|
| 表格渲染回歸 | 高 | 使用 edit.pdf 和 edit3.pdf 作為回歸測試 |
| 記憶體管理變更導致 OOM | 高 | 保留現有閾值，僅重構代碼結構 |
| 服務重構導致處理失敗 | 中 | 逐步重構，每階段完整測試 |
Success Metrics
| 指標 | 目前 | 目標 |
|---|---|---|
| edit3.pdf Direct Track cells | 204 (錯誤) | 83 (正確) |
| OCR Track 圖片放回率 | 0% | 100% |
| cell_boxes 座標正確率 | ~40% | 100% |
| OCRService 行數 | 2,326 | < 800 |
| PDFGeneratorService 行數 | 4,644 | < 2,000 |