From cd48930044b4e840aa11c69d16542c910363cf04 Mon Sep 17 00:00:00 2001 From: philipcheung Date: Sat, 12 Sep 2026 00:38:47 +0800 Subject: [PATCH] Add R2 image upload design spec --- .../2026-09-12-r2-image-upload-design.md | 205 ++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-12-r2-image-upload-design.md diff --git a/docs/superpowers/specs/2026-09-12-r2-image-upload-design.md b/docs/superpowers/specs/2026-09-12-r2-image-upload-design.md new file mode 100644 index 0000000..bf5e5bb --- /dev/null +++ b/docs/superpowers/specs/2026-09-12-r2-image-upload-design.md @@ -0,0 +1,205 @@ +# 後台圖片上傳（Cloudflare R2）(Design Spec) + +- **日期**：2026-09-12 +- **狀態**：已與客戶確認方向 +- **背景**：後台有 4 個圖片欄位，現時一律要手動貼外部圖片 URL（`網站設定` 的 `hero_image` / `og_image`、`完成案例` 的 `imageUrl`、`文章` 的 `coverImage`）。客戶想可以直接上傳，圖片存喺 Cloudflare R2。 +- **相關**：`2026-09-11-structure-ai-deploy-design.md`（單一 Worker + D1 + KV 架構）依然有效。本 spec 新增 R2 binding 同兩個 endpoint。 + +--- + +## 1. 目標與非目標 + +### 目標 + +1. 4 個圖片欄位全部可以由「揀檔即時上傳」取代手動貼 URL，**同時保留**貼 URL 能力（progressive enhancement）。 +2. 圖片存喺 R2，由同一個 Worker 經 `/media/*` 路由送出，唔需要公開 bucket 或額外網域。 +3. 上傳時喺瀏覽器端縮圖（最大寬 1600px）並轉 WebP（約 85% 質素）先上傳，零伺服器成本、零新依賴。 +4. 換圖或刪除內容時，自動刪除對應舊 R2 檔。 + +### 非目標 (Out of scope) + +- **唔支援** Blog 內文（Markdown）插圖上傳。 +- **唔改** DB schema、**唔加** migration（圖片欄位本身已係 text）。 +- **唔做**伺服器端圖片處理（WASM / Cloudflare Images），**唔引入** React / Chakra 落後台。 +- **唔做**獨立媒體庫頁、圖片裁切、alt text 管理。 +- 冇圖片版本控制 / 歷史。 + +--- + +## 2. 架構 + +### 2.1 R2 binding + +`wrangler.jsonc` 加： + +```jsonc +"r2_buckets": [ + { "binding": "MEDIA", "bucket_name": "yingfung-solar-media" } +] +``` + +同 D1 / KV 唔同，R2 binding 用固定 `bucket_name`，**冇 id placeholder**，唔使 `setup.mjs` 寫 id。本機靠現有 `astro.config.mjs` 的 `platformProxy` 讀 binding，R2 物件存喺 `.wrangler/state`（已 gitignore）。 + +`src/lib/env.ts` 的 `AppEnv` 加 `MEDIA: R2Bucket`。 + +### 2.2 上傳 endpoint — `/admin/upload` + +`src/pages/admin/upload.ts`，`export const prerender = false`，`POST` only： + +- 由 `middleware.ts` 既有 `/admin` 保護（未登入導向 login）。 +- 收 `multipart/form-data`：`file`（File）、`scope`（`settings` | `cases` | `posts`）。 +- 驗證： + - 類型只准 `image/webp`、`image/jpeg`、`image/png`、`image/gif`；**拒絕 SVG**（避免 XSS）。 + - 大小上限 8MB（client 已縮圖，正常遠低於此）。 + - `scope` 唔合法 → 400。 +- Key：`/.`，`ext` 由實際 MIME type 決定（`image/webp`→`webp`、`image/jpeg`→`jpg`、`image/png`→`png`、`image/gif`→`gif`）。client 正常會轉 webp，故多數係 `.webp`。 +- `await env.MEDIA.put(key, await file.arrayBuffer(), { httpMetadata: { contentType: file.type } })`。 +- 回 `{ ok: true, url: "/media/" }`；失敗回 `{ ok: false, error: "<中文訊息>" }`（HTTP 400/500），**唔 throw**。 + +### 2.3 出圖 endpoint — `/media/[...key]` + +`src/pages/media/[...key].ts`，`export const prerender = false`，`GET`： + +- `const key = Astro.params.key`（rest param）。 +- `const obj = await getEnv().MEDIA.get(key)`；`null` → 404。 +- Header： + - `Content-Type`：`obj.httpMetadata?.contentType ?? "application/octet-stream"`。 + - `Cache-Control: public, max-age=31536000, immutable`（key 含 uuid，內容不可變）。 + - `ETag`：用 `obj.httpEtag`；若 request 帶 `If-None-Match` 相同 → 回 304。 +- 回 `new Response(obj.body, { headers })`。 + +`/media/*` 係公開（前台圖片要讀）；只有上傳要認證。 + +### 2.4 Client 端增強 + +**共用元件 `src/components/admin/ImageField.astro`**（新資料夾 `src/components/admin/`）render： + +- 一個 `type="text"` 欄（原本嘅 URL 欄，保留貼 URL）。 +- 一個 `type="file" accept="image/*"`。 +- 一個 `` 預覽（有值先顯示）。 +- 一個狀態文字 span（上傳中 / ✓ 已上傳 / 錯誤）。 + +Props：`name`、`label`、`value`、`scope`、`id`。 + +**共用 script**：寫喺 `AdminLayout.astro`（全站後台載入一次），偵測 `[data-image-field]`： + +1. `change` 事件：`createImageBitmap(file)` → 計 scale = `min(1, 1600 / width)` → 畫落 canvas → `canvas.toBlob(..., "image/webp", 0.85)`。 +2. `toBlob` 回 null（瀏覽器唔支援 WebP）→ fallback 用原檔。 +3. `fetch POST /admin/upload`（`FormData`：`file` + `scope`）。 +4. 成功 → 將 `url` 寫入 URL 欄、更新預覽 `src`、顯示「✓ 已上傳」。 +5. 失敗 → 顯示錯誤訊息，保留原 URL 欄值。 +6. 若 JS 失效 → 用戶仍可貼 URL，主表單照常運作。 + +**主表單不變**：`settings.astro` / `cases.astro` / `post/[id].astro` 繼續 `parseForm` + Zod，只係收到 `/media/...` 字串。 + +**OG image**：`Base.astro` 已會將相對 `image` 轉絕對 URL（`new URL(image, origin)`），所以 `og_image` / `coverImage` 用 `/media/...` 冇問題。 + +--- + +## 3. 欄位與設定 + +`src/data/settings-fields.ts`： + +- `FieldType` 加 `"image"`。 +- `hero_image`、`og_image` 由 `type: "url"` 改為 `type: "image"`。 + +`src/pages/admin/settings.astro`： + +- image 型別 render `ImageField`（scope `settings`）；textarea / text / url 維持原本。 + +`src/pages/admin/cases.astro`：新增表單同每張卡嘅圖片欄改用 `ImageField`（scope `cases`）。 + +`src/pages/admin/post/[id].astro`：`coverImage` 欄改用 `ImageField`（scope `posts`）。 + +--- + +## 4. 自動刪除舊圖 + +新 `src/lib/media.ts`： + +- `MEDIA_PREFIX = "/media/"`；`mediaUrl(key)` → `/media/`。 +- `deleteMedia(env, url)`：只當 `url` 以 `/media/` 開頭才 `env.MEDIA.delete(key)`；外部 URL、空值一律唔理，唔 throw。 + +呼叫位置： + +| 檔案 | 時機 | +|---|---| +| `cases.astro` | `save`：比對 DB 舊 `imageUrl` 同新值，唔同先刪舊。`delete`：刪除該案例圖片。 | +| `post/[id].astro` | `save`：比對 `existing.coverImage` 同新值。`delete`：刪除封面。 | +| `settings.astro` | 每個 image key upsert 前攞舊值，唔同先刪舊。 | + +`cases.astro` 目前 update 前冇 select，需要先攞現有 row 做比對。 + +### 已知取捨 + +- 同一個 `/media/...` URL 若被貼去多過一個欄位，刪其中一個會令另一個爛圖。單一管理員情境可接受，spec 標明。 +- 舊值若係外部 URL（唔係 `/media/`）唔會刪。 + +--- + +## 5. 設定 / 部署改動 + +| 檔案 | 改動 | +|---|---| +| `wrangler.jsonc` | 加 `r2_buckets`（binding `MEDIA`） | +| `astro.config.mjs` | 唔使改（`platformProxy` 已讀 wrangler bindings） | +| `src/lib/env.ts` | `AppEnv` 加 `MEDIA: R2Bucket` | +| `package.json` | 加 `"r2:create": "wrangler r2 bucket create yingfung-solar-media"` | +| `scripts/setup.mjs` | 加建立 R2 bucket 步驟（idempotent，已存在就略過），令一鍵 setup 完整 | +| `.dev.vars.example` | 唔使改（R2 係 binding，唔係 secret） | +| `worker-configuration.d.ts` | 跑 `npm run types` 重新產生 | + +--- + +## 6. 檔案改動總表 + +| 檔案 | 改動 | +|---|---| +| `wrangler.jsonc` | 加 R2 binding | +| `package.json` | 加 `r2:create` | +| `scripts/setup.mjs` | 建 R2 bucket | +| `src/lib/env.ts` | `AppEnv.MEDIA` | +| `src/lib/media.ts` | 新：`MEDIA_PREFIX` / `mediaUrl` / `deleteMedia` | +| `src/pages/admin/upload.ts` | 新：上傳 endpoint | +| `src/pages/media/[...key].ts` | 新：出圖 endpoint | +| `src/components/admin/ImageField.astro` | 新：圖片欄元件 | +| `src/layouts/AdminLayout.astro` | 加 client 端縮圖／上傳 script + image field 樣式 | +| `src/pages/admin/settings.astro` | image 型別用 ImageField + 換圖刪舊 | +| `src/pages/admin/cases.astro` | ImageField + 換圖／刪除清理 | +| `src/pages/admin/post/[id].astro` | ImageField + 換封面／刪文清理 | +| `src/data/settings-fields.ts` | `FieldType` 加 `image`；hero/og 改型別 | +| `src/schemas/*` | 唔使改（URL 仍係 string） | +| `src/db/schema.ts` / `migrations/` | **唔使改** | + +### DOX 更新 + +- `src/AGENTS.md`：Admin「圖片一律 URL（暫無上傳）」改為描述上傳流程；加 `/admin/upload`、`/media/*` endpoint。 +- `src/lib/AGENTS.md`：加 `media.ts`；`env.ts` 加 `MEDIA`。 +- `src/data/AGENTS.md`：`FieldType` 加 `image`。 +- 根 `AGENTS.md`：R2 binding、`r2:create`、`MEDIA`。 + +--- + +## 7. 驗證 + +冇 test / lint script；`npm run build` 係唯一 build 驗證。 + +手動（`npm run dev` :4321，需先 `npm run r2:create` 或靠本機模擬 R2）： + +1. 4 個位各上傳一張圖 → URL 欄自動填 `/media/...`、預覽正常顯示。 +2. 直接開 `/media/` → 出圖、有 `Cache-Control` 同 `ETag`；亂打 key → 404。 +3. 換圖後 → 舊 `/media/...` 變 404（已刪）。 +4. 刪除案例 / 文章 → 對應圖變 404。 +5. 貼外部 URL（唔上傳）→ 照樣儲存同顯示。 +6. 上傳 SVG / 超大檔 → 顯示中文錯誤、唔會寫入。 +7. `npm run build` 成功。 + +--- + +## 8. 決策記錄 + +- **Worker 路由 `/media/*`** 而唔用公開 R2 網域：唔使改 Cloudflare 設定、本機 dev 一致、可自控 cache header。代價係圖片經 Worker request（小型官網可接受）。 +- **瀏覽器端轉 WebP**：免費、唔食 Worker CPU（免費 plan 10ms/request 限制）、零依賴。代價係依賴瀏覽器（單一管理員用現代瀏覽器，且保留 fallback）。 +- **保留貼 URL**：漸進增強，JS 失效都可用，亦兼容外部圖。 +- **自動刪舊圖**：客戶選擇；用 uuid key 避免誤刪同名檔。 +- **拒絕 SVG**：避免 inline SVG XSS。