940a406dce
Backup commit before executing remove-unused-code proposal. This includes all pending changes and new features. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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 |
|