feat: add storage cleanup mechanism with soft delete and auto scheduler

- Add soft delete (deleted_at column) to preserve task records for statistics
- Implement cleanup service to delete old files while keeping DB records
- Add automatic cleanup scheduler (configurable interval, default 24h)
- Add admin endpoints: storage stats, cleanup trigger, scheduler status
- Update task service with admin views (include deleted/files_deleted)
- Add frontend storage management UI in admin dashboard
- Add i18n translations for storage management

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
egg
2025-12-14 12:41:01 +08:00
parent 81a0a3ab0f
commit 73112db055
23 changed files with 1359 additions and 634 deletions

View File

@@ -1,82 +0,0 @@
# 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-pdfi18n 由 `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 GPUCUDA 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/`:系統規格與歷史變更