# Change: Add Storage Cleanup Mechanism ## Why 目前系統缺乏完整的磁碟空間管理機制: - `delete_task` 只刪除資料庫記錄,不刪除實際檔案 - `auto_cleanup_expired_tasks` 存在但從未被調用 - 上傳檔案 (uploads/) 和結果檔案 (storage/results/) 會無限累積 用戶需要: 1. 定期清理過期檔案以節省磁碟空間 2. 保留資料庫記錄以便管理員查看累計統計(TOKEN、成本、用量) 3. 軟刪除機制讓用戶可以「刪除」任務但不影響統計 ## What Changes ### Backend Changes 1. **Task Model 擴展** - 新增 `deleted_at` 欄位實現軟刪除 - 保留現有 `file_deleted` 欄位追蹤檔案清理狀態 2. **Task Service 更新** - `delete_task()` 改為軟刪除(設置 `deleted_at`,不刪檔案) - 用戶查詢自動過濾 `deleted_at IS NOT NULL` 的記錄 - 新增 `cleanup_expired_files()` 方法清理過期檔案 3. **Cleanup Service 新增** - 定期排程任務(可配置間隔,建議每日) - 清理邏輯:每用戶保留最新 N 筆任務的檔案(預設 50) - 只刪除檔案,不刪除資料庫記錄(保留統計數據) 4. **Admin Endpoints 擴展** - 新增 `/api/v2/admin/tasks` 端點:查看所有任務(含已刪除) - 支援過濾:`include_deleted=true/false`、`include_files_deleted=true/false` ### Frontend Changes 5. **Task History Page** - 用戶只看到自己的任務(已有 user_id 隔離) - 軟刪除的任務不顯示在列表中 6. **Admin Dashboard** - 新增任務管理視圖 - 顯示所有任務含狀態標記(已刪除、檔案已清理) - 可查看累計統計不受刪除影響 ### Configuration 7. **Config 新增設定項** - `cleanup_interval_hours`: 清理間隔(預設 24) - `max_files_per_user`: 每用戶保留最新檔案數(預設 50) - `cleanup_enabled`: 是否啟用自動清理(預設 true) ## Impact - Affected specs: `task-management` - Affected code: - `backend/app/models/task.py` - 新增 deleted_at 欄位 - `backend/app/services/task_service.py` - 軟刪除和查詢邏輯 - `backend/app/services/cleanup_service.py` - 新檔案 - `backend/app/routers/admin.py` - 新增端點 - `backend/app/core/config.py` - 新增設定 - `frontend/src/pages/AdminDashboardPage.tsx` - 任務管理視圖 - Database migration required: 新增 `deleted_at` 欄位