test

openspec/changes/refactor-dual-track-architecture/proposal.md

@@ -0,0 +1,68 @@
+# Change: Refactor Dual-Track Architecture
+
+## Why
+
+目前雙軌制 OCR 系統存在多個已知問題和架構債務：
+
+1. **Direct Track 表格問題**: `_detect_tables_by_position()` 無法識別合併單元格，導致 edit3.pdf 產生 204 個錯誤拆分的 cells（應為 83 個）
+2. **OCR Track 圖片路徑丟失**: CHART/DIAGRAM 等視覺元素的 `saved_path` 在轉換時丟失，導致圖片未放回 PDF
+3. **OCR Track cell_boxes 座標錯亂**: PP-StructureV3 返回的 cell_boxes 超出頁面邊界
+4. **服務層過度複雜**: OCRService (2,326 行) 承擔過多職責，難以維護和測試
+5. **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 |