# 刪除 API

本頁說明 `DELETE /del/*path` 如何把檔案或資料夾移入依日期分桶的回收桶，以及如何還原。

## 請求

```bash
# 刪除單一檔案
curl -X DELETE http://localhost:8080/del/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg

# 刪除整個資料夾
curl -X DELETE http://localhost:8080/del/blog/2025
```

`*path` 相對於 `storage/image/upload/`，可指向檔案或資料夾。

## 搬移規則

| 步驟 | 行為 |
|---|---|
| 1 | `os.Stat` 確認目標存在並判斷是否為資料夾 |
| 2 | 建立 `storage/image/upload/.trash/YYYY-MM-DD/`（伺服器本地日期） |
| 3 | 目的地為 `.trash/YYYY-MM-DD/{檔名或資料夾名}`，只保留最後一段名稱，不保留原父路徑 |
| 4 | 同日已有同名項目時改名為 `{名}_{毫秒時間戳}{副檔名}` |
| 5 | `os.Rename` 搬移 |

回收桶位於 `upload/` 底下，但以 `.` 開頭；Nginx 的 `location ~ /\.` 會拒絕任何含 `/.` 的路徑，因此無法經由 Nginx 讀取回收桶內的檔案。

## 回應

| 狀態碼 | 內容 | 情境 |
|---|---|---|
| `200` | `{"success":1,"message":"move path to: ..."}` | 檔案已搬移 |
| `200` | `{"success":1,"message":"move folder to: ..."}` | 資料夾已搬移 |
| `400` | `please assign a path first` | `*path` 為空 |
| `400` | `path not found: ...` | 目標不存在 |
| `400` | `can not create folder: ...`／`can not move file: ...` | 建立回收桶或搬移失敗 |
| `408` | `timed out` | 超過 30 秒 |

`message` 中的路徑為伺服器上的絕對路徑。

## 還原與快取

還原時把項目從 `.trash/YYYY-MM-DD/` 移回 `storage/image/upload/` 下的原位置即可。刪除不會清除轉檔快取，已產生的尺寸版本會繼續被回傳，見 [快取分層](/zh/caching#失效與清除)。