# 上傳 API

本頁說明 `POST /upload/{path}` 的請求格式、檔名規則與回應。

## 請求

| 項目 | 值 |
|---|---|
| 方法 | `POST` |
| 路徑 | `/upload/{path}`，`{path}` 為 `storage/image/upload/` 下的目標資料夾，可含 `/`，不存在時遞迴建立 |
| 格式 | `multipart/form-data` |
| 檔案欄位 | `filepath`（單檔） |
| 大小上限 | 應用程式無限制；經 Nginx 時為 `client_max_body_size 100M` |

## 支援格式

依用戶端送出的 MIME 類型判斷：

| MIME | 儲存副檔名 |
|---|---|
| `image/jpg`、`image/jpeg` | `.jpg` |
| `image/png` | `.png` |
| `image/webp` | `.webp` |
| `image/svg+xml` | `.svg` |
| `application/pdf` | `.pdf` |

## 檔名

`{16 字元隨機英數}_{毫秒時間戳記}.{ext}`，例：`ERftP1gTS7WCTeJ8_1744080848530.jpg`。原始檔名不保留。

## 回應

| 狀態 | 型別 | 內容 |
|---|---|---|
| `201` | JSON | `{ success: 1, filename, type, size, src }` |
| `400` | 文字 | `請至少規劃一個資料夾位置`（`{path}` 為空） |
| `400` | 文字 | `僅支持 jpg / png / webp / svg / pdf` |
| `400` | 文字 | multer 錯誤訊息（如欄位名稱不是 `filepath` 時的 `"Unexpected field"`） |
| `500` | 文字 | `檔案不存在或上傳失敗`（請求中沒有檔案） |

`src` 依 `NODE_ENV` 組成：`development` 為 `http://localhost:8080/c/img/{path}/{filename}`，其他為 `https://{DOMAIN}/c/img/{path}/{filename}`。

## 範例

```bash
curl -fsS -X POST \
  -F "filepath=@./photo.png" \
  http://localhost:8080/upload/products/2025 \
  || echo "上傳失敗"
```