# Tool_OCR 架構說明與 UML

本文件概覽 Tool_OCR 的主要組件、資料流與雙軌處理（OCR / Direct），並附上 UML 關係圖以協助判斷改動的影響範圍。

## 系統分層與重點元件
- **API 層（FastAPI）**：`app/main.py` 啟動應用、掛載路由（`routers/auth.py`, `routers/tasks.py`, `routers/admin.py`），並在 lifespan 初始化記憶體管理、服務池與併發控制。
- **任務/檔案管理**：`task_service.py` 與 `file_access_service.py` 掌管任務 CRUD、路徑與權限；`Task` / `TaskFile` 模型紀錄結果檔路徑。
- **核心處理服務**：`OCRService`（`services/ocr_service.py`）負責雙軌路由與 OCR；整合偵測、直抽、OCR、統一格式轉換、匯出與 PDF 生成。
- **雙軌偵測/直抽**：`DocumentTypeDetector` 判斷走 Direct 或 OCR；`DirectExtractionEngine` 使用 PyMuPDF 直接抽取文字/表格/圖片（必要時觸發混合模式補抽圖片）。
- **OCR 解析**：PaddleOCR + `PPStructureEnhanced` 抽取 23 類元素；`OCRToUnifiedConverter` 轉成 `UnifiedDocument` 統一格式。
- **匯出/呈現**：`UnifiedDocumentExporter` 產出 JSON/Markdown；`pdf_generator_service.py` 產生版面保持 PDF；前端透過 `/api/v2/tasks/{id}/download/*` 取得。
- **資源控管**：`memory_manager.py`（MemoryGuard、prediction semaphore、模型生命週期），`service_pool.py`（`OCRService` 池）避免多重載模與 GPU 爆滿。
- **翻譯與預覽**：`translation_service` 針對已完成任務提供異步翻譯（`/api/v2/translate/*`），`layout_preprocessing_service` 提供預處理預覽與品質指標（`/preview/preprocessing` → `/preview/image`）。

## 處理流程（任務層級）
1. **上傳**：`POST /api/v2/upload` 建立 Task 並寫檔到 `uploads/`（含 SHA256、檔案資訊）。
2. **啟動**：`POST /api/v2/tasks/{id}/start`（`ProcessingOptions`，可含 `pp_structure_params`）→ 背景 `process_task_ocr` 取得服務池中的 `OCRService`。
3. **軌道決策**：`DocumentTypeDetector.detect` 分析 MIME、PDF 文字覆蓋率或 Office 轉 PDF 後的抽樣結果：
   - **Direct**：`DirectExtractionEngine.extract` 產出 `UnifiedDocument`；若偵測缺圖則啟用混合模式呼叫 OCR 抽圖或渲染 inline 圖。
   - **OCR**：`process_file_traditional` → PaddleOCR + PP-Structure → `OCRToUnifiedConverter.convert` 產生 `UnifiedDocument`。
   - 以 `ProcessingTrack` 記錄 `ocr` / `direct` / `hybrid`，處理時間與統計寫入 metadata。
4. **輸出保存**：`UnifiedDocumentExporter` 寫 `_result.json`（含 metadata、statistics）與 `_output.md`；`pdf_generator_service` 產出 `_layout.pdf`；路徑回寫 DB。
5. **下載/檢視**：前端透過 `/download/json|markdown|pdf|unified` 取檔；`/metadata` 讀 JSON metadata 回傳統計與 `processing_track`。

## 前端流程摘要
- `UploadPage`：呼叫 `apiClientV2.uploadFile`，首個 `task_id` 存於 `uploadStore.batchId`。
- `ProcessingPage`：對 `batchId` 呼叫 `startTask`（預設 `use_dual_track=true`，支援自訂 `pp_structure_params`），輪詢狀態。
- `ResultsPage` / `TaskDetailPage`：使用 `getTask` 與 `getProcessingMetadata` 顯示 `processing_track`、統計並提供 JSON/Markdown/PDF/Unified 下載。
- `TaskHistoryPage`：列出任務、支援重新啟動、重試、下載。

## 共同模組與影響點
- **UnifiedDocument**（`models/unified_document.py`）為 Direct/OCR 共用輸出格式；所有匯出/PDF/前端 track 顯示依賴其欄位與 metadata。
- **服務池/記憶體守護**：Direct 與 OCR 共用同一 `OCRService` 實例池與 MemoryGuard；新增資源或改動需確保遵循 acquire/release、清理與 semaphore 規則。
- **偵測閾值變更**：`DocumentTypeDetector` 參數調整會影響 Direct 與 OCR 分流比例，間接改變 GPU 載荷與結果格式。
- **匯出/PDF**：任何 UnifiedDocument 結構變動會影響 JSON/Markdown/PDF 產出與前端下載/預覽；需同步維護轉換與匯出器。

## UML 關係圖（Mermaid）
```mermaid
classDiagram
    class TasksRouter {
      +upload_file()
      +start_task()
      +download_json/markdown/pdf/unified()
      +get_metadata()
    }
    class TaskService {+create_task(); +update_task_status(); +get_task_by_id()}
    class FileAccessService
    class OCRService {
      +process()
      +process_with_dual_track()
      +process_file_traditional()
      +save_results()
    }
    class DocumentTypeDetector {+detect()}
    class DirectExtractionEngine {+extract(); +check_document_for_missing_images()}
    class OCRToUnifiedConverter {+convert()}
    class UnifiedDocument
    class UnifiedDocumentExporter {+export_to_json(); +export_to_markdown()}
    class PDFGeneratorService {+generate_layout_pdf(); +generate_from_unified_document()}
    class ServicePool {+acquire(); +release()}
    class MemoryManager <<singleton>>
    class OfficeConverter {+convert_to_pdf()}
    class PPStructureEnhanced {+analyze_with_full_structure()}

    TasksRouter --> TaskService
    TasksRouter --> FileAccessService
    TasksRouter --> OCRService : background process via process_task_ocr
    OCRService --> DocumentTypeDetector : track recommendation
    OCRService --> DirectExtractionEngine : direct track
    OCRService --> OCRToUnifiedConverter : OCR track result -> UnifiedDocument
    OCRService --> OfficeConverter : Office -> PDF
    OCRService --> PPStructureEnhanced : layout analysis (PP-StructureV3)
    OCRService --> UnifiedDocumentExporter : persist results
    OCRService --> PDFGeneratorService : layout-preserving PDF
    OCRService --> ServicePool : acquired instance
    ServicePool --> MemoryManager : model lifecycle / GPU guard
    UnifiedDocumentExporter --> UnifiedDocument
    PDFGeneratorService --> UnifiedDocument
```

## 影響判斷指引
- **改 Direct/偵測邏輯**：會改變 `processing_track` 與結果格式；前端顯示與下載 JSON/Markdown/PDF 仍依賴 UnifiedDocument，需驗證匯出與 PDF 生成。
- **改 OCR/PP-Structure 參數**：僅影響 OCR track；Direct track 不受 `pp_structure_params` 影響（符合 spec），需維持 `processing_track` 填寫。
- **改 UnifiedDocument 結構/統計**：需同步 `UnifiedDocumentExporter`、`pdf_generator_service`、前端 `getProcessingMetadata`/下載端點。
- **改資源控管**：服務池或 MemoryGuard 調整會同時影響 Direct/OCR 執行時序與穩定性，須確保 acquire/release 與 semaphore 不被破壞。