# Tool_OCR

多語系批次 OCR 與版面還原工具，提供直接抽取與深度 OCR 雙軌流程、PP-StructureV3 結構分析、JSON/Markdown/版面保持 PDF 匯出，前端以 React 提供任務追蹤與下載。

## 功能亮點
- 雙軌處理：DocumentTypeDetector 選擇 Direct (PyMuPDF 抽取) 或 OCR (PaddleOCR + PP-StructureV3)，必要時混合補圖。
- 統一輸出：OCR/Direct 皆轉成 UnifiedDocument，後續匯出 JSON/Markdown/版面保持 PDF，並回寫 metadata。
- 資源控管：OCRServicePool、MemoryGuard 與 prediction semaphore 控制 GPU/CPU 載荷，支援自動卸載與 CPU fallback。
- 任務與權限：JWT 驗證、外部登入 API、任務歷史/統計、管理員審計路由。
- 前端體驗：React + Vite + shadcn/ui，任務輪詢、結果預覽、下載、設定頁與管理面板。
- 國際化：保留翻譯流水線（translation_service），可接入 Dify/離線模型。

## 架構概覽
- **Backend (FastAPI)**  
  - `app/main.py`：lifespan 初始化 service pool、memory manager、CORS、/health；上傳端點 `/api/v2/upload`。  
  - `routers/`：`auth.py` 登入、`tasks.py` 任務啟動/下載/metadata、`admin.py` 審計、`translate.py` 翻譯輸出。  
  - `services/`：`ocr_service.py` 雙軌處理、`document_type_detector.py` 軌道選擇、`direct_extraction_engine.py` 直抽、`pp_structure_enhanced.py` 版面分析、`ocr_to_unified_converter.py` 與 `unified_document_exporter.py` 匯出、`pdf_generator_service.py` 版面保持 PDF、`service_pool.py`/`memory_manager.py` 資源管理。  
  - `models/`、`schemas/`：SQLAlchemy 模型與 Pydantic 結構，`core/config.py` 整合環境設定。
- **Frontend (React 18 + Vite)**  
  - `src/pages`：Login、Upload、Processing、Results、Export、TaskHistory/TaskDetail、Settings、AdminDashboard、AuditLogs。  
  - `src/services` API client + React Query，`src/store` 任務/使用者狀態，`src/components` 共用 UI。  
  - PDF 預覽使用 react-pdf，i18n 由 `src/i18n` 管理。
- **處理流程摘要**  
  1. `/api/v2/upload` 儲存檔案至 `backend/uploads` 並建立 Task。  
  2. `/api/v2/tasks/{id}/start` 觸發雙軌處理（可附 `pp_structure_params`）。  
  3. Direct/OCR 產生 UnifiedDocument，匯出 `_result.json`、`_output.md`、版面保持 PDF 至 `backend/storage/results/<task_id>/`，並在 DB 記錄 metadata。  
  4. `/api/v2/tasks/{id}/download/{json|markdown|pdf|unified}` 與 `/metadata` 提供下載與統計。

## 倉庫結構
- `backend/app/`：FastAPI 程式碼（core、routers、services、schemas、models、main.py）。
- `backend/tests/`：測試集合  
  - `api/` API mock/integration、`services/` 核心邏輯、`e2e/` 需啟動後端與測試帳號、`performance/` 量測、`archived/` 舊案例。  
  - 測試資源使用 `demo_docs/` 中的範例檔（gitignore，不會上傳）。
- `backend/uploads`, `backend/storage`, `backend/logs`, `backend/models/`：執行時輸入/輸出/模型/日誌目錄，啟動時自動建立並鎖定在 backend 目錄下。
- `frontend/`：React 應用程式碼與設定（vite.config.ts、eslint.config.js 等）。
- `docs/`：API/架構/風險說明。
- `openspec/`：規格檔與變更紀錄。

## 環境準備
- 需求：Python 3.10+、Node 18+/20+、MySQL（或相容端點）、可選 NVIDIA GPU（CUDA 11.8+/12.x）。  
- 一鍵腳本：`./setup_dev_env.sh`（可加 `--cpu-only`、`--skip-db`）。  
- 手動：
  1. `python3 -m venv venv && source venv/bin/activate`
  2. `pip install -r requirements.txt`
  3. `cp .env.example .env.local` 並填入 DB/認證/路徑設定（預設使用 8000/5173）
  4. `cd frontend && npm install`

## 開發啟動
- Backend（預設 `.env` 的 `BACKEND_PORT=8000`，config 預設 12010，依環境變數覆蓋）：  
  ```bash
  source venv/bin/activate
  cd backend
  uvicorn app.main:app --reload --host 0.0.0.0 --port ${BACKEND_PORT:-8000}
  # API docs: http://localhost:${BACKEND_PORT:-8000}/docs
  ```
  `Settings` 會將 `uploads`/`storage`/`logs`/`models` 等路徑正規化到 `backend/`，避免在不同工作目錄產生多餘資料夾。
- Frontend：  
  ```bash
  cd frontend
  npm run dev -- --host --port ${FRONTEND_PORT:-5173}
  # http://localhost:${FRONTEND_PORT:-5173}
  ```
- 也可用 `./start.sh backend|frontend|--stop|--status` 管理背景進程（PID 置於 `.pid/`）。

## 測試
- 單元/整合：`pytest backend/tests -m "not e2e"`（如需）。  
- API mock 測試：`pytest backend/tests/api`（僅依賴虛擬依賴/SQLite）。  
- E2E：需先啟動後端並準備測試帳號，預設呼叫 `http://localhost:8000/api/v2`，測試檔使用 `demo_docs/` 範例檔。  
- 性能/封存案例：`backend/tests/performance`、`backend/tests/archived` 可選擇性執行。

## 產生物與清理
- 執行後的輸入/輸出皆位於 `backend/uploads`、`backend/storage/results|json|markdown|exports`、`backend/logs`，模型快取在 `backend/models/`。  
- 已移除多餘的 `node_modules/`、`venv/`、舊的 `pp_demo/` 與上傳/輸出/日誌樣本。再次清理可執行：
  ```bash
  rm -rf backend/uploads/* backend/storage/results/* backend/logs/*.log .pytest_cache backend/.pytest_cache
  ```
  目錄會在啟動時自動重建。

## 參考文件
- `docs/architecture-overview.md`：雙軌流程與組件說明  
- `docs/API.md`：主要 API 介面  
- `openspec/`：系統規格與歷史變更