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，依環境變數覆蓋）：

  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：

  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/ 與上傳/輸出/日誌樣本。再次清理可執行：

  rm -rf backend/uploads/* backend/storage/results/* backend/logs/*.log .pytest_cache backend/.pytest_cache
  

  目錄會在啟動時自動重建。

參考文件

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