From 47f14b79e397f33027b2da471f94a216c0fb917e Mon Sep 17 00:00:00 2001
From: philipcheung <zerophilip2013hk@gmail.com>
Date: Sat, 12 Sep 2026 00:39:48 +0800
Subject: [PATCH] Add R2 image upload implementation plan

---
 .../plans/2026-09-12-r2-image-upload.md       | 999 ++++++++++++++++++
 1 file changed, 999 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-12-r2-image-upload.md

diff --git a/docs/superpowers/plans/2026-09-12-r2-image-upload.md b/docs/superpowers/plans/2026-09-12-r2-image-upload.md
new file mode 100644
index 0000000..fb5e73d
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-12-r2-image-upload.md
@@ -0,0 +1,999 @@
+# R2 Image Upload Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 後台 4 個圖片欄位（`hero_image`、`og_image`、案例 `imageUrl`、文章 `coverImage`）支援揀檔即時上傳去 Cloudflare R2，同時保留貼 URL。
+
+**Architecture:** 單一 Worker 加一個 R2 binding `MEDIA`；`/admin/upload`（受 middleware 保護）收檔寫入 R2，`/media/*` 公開讀出。瀏覽器端用 Canvas 縮到最大寬 1600px、轉 WebP 再上傳。舊圖喺換圖／刪除時由 `src/lib/media.ts` 的 `deleteMedia` 清理。**唔改 DB schema、唔加 migration。**
+
+**Tech Stack:** Astro 7（`output: "static"` + per-page SSR）、Cloudflare Workers + R2、Drizzle/D1、Zod、原生 Canvas／fetch（後台唔引入 React）。
+
+**Spec:** `docs/superpowers/specs/2026-09-12-r2-image-upload-design.md`
+
+**重要：呢個專案冇 test / lint script。每個 task 的驗證係 `npm run build`（唯一 build 驗證）＋ 有需要時 `npm run dev` 手動測。冇單元測試框架，所以步驟用 build + 手動檢查取代 TDD。**
+
+---
+
+## File Structure
+
+| 檔案 | 責任 |
+|---|---|
+| `wrangler.jsonc` | R2 binding（`MEDIA`） |
+| `package.json` | `r2:create` script |
+| `scripts/setup.mjs` | 一鍵 setup 建 R2 bucket |
+| `src/lib/env.ts` | `AppEnv.MEDIA` |
+| `src/lib/media.ts`（新） | `/media/` prefix、URL↔key、`deleteMedia` |
+| `src/pages/admin/upload.ts`（新） | 上傳 endpoint |
+| `src/pages/media/[...key].ts`（新） | 出圖 endpoint |
+| `src/components/admin/ImageField.astro`（新） | 圖片欄元件（URL 欄 + file input + 預覽 + 狀態） |
+| `src/layouts/AdminLayout.astro` | client 端縮圖／上傳 script + image field 樣式 |
+| `src/data/settings-fields.ts` | `FieldType` 加 `image`；hero/og 改型別 |
+| `src/pages/admin/settings.astro` | image 型別用 ImageField + 換圖刪舊 |
+| `src/pages/admin/cases.astro` | ImageField + 換圖／刪除清理 |
+| `src/pages/admin/post/[id].astro` | ImageField + 換封面／刪文清理 |
+
+**唔郁：** `src/db/schema.ts`、`migrations/**`、`src/schemas/*`（圖片仍係字串）。
+
+---
+
+### Task 1: R2 binding、env 型別同 setup 指令
+
+**Files:**
+- Modify: `wrangler.jsonc`
+- Modify: `package.json`
+- Modify: `scripts/setup.mjs`
+- Modify: `src/lib/env.ts`
+
+- [ ] **Step 1: `wrangler.jsonc` 加 R2 binding**
+
+喺 `"kv_namespaces": [...]` 之後（結尾 `]` 加逗號）加：
+
+```jsonc
+  "r2_buckets": [
+    {
+      "binding": "MEDIA",
+      "bucket_name": "yingfung-solar-media"
+    }
+  ]
+```
+
+完整 `wrangler.jsonc` 應該係：
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "yingfung-solar",
+  "main": "@astrojs/cloudflare/entrypoints/server",
+  "compatibility_date": "2026-09-10",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "not_found_handling": "404-page"
+  },
+
+  "observability": {
+    "enabled": true,
+    "logs": { "enabled": true }
+  },
+
+  "vars": {
+    "SITE_NAME": "盈豐太陽能"
+  },
+
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "yingfung-solar-db",
+      "database_id": "PASTE_D1_DATABASE_ID_HERE"
+    }
+  ],
+  "kv_namespaces": [
+    {
+      "binding": "CACHE",
+      "id": "PASTE_KV_NAMESPACE_ID_HERE"
+    }
+  ],
+  "r2_buckets": [
+    {
+      "binding": "MEDIA",
+      "bucket_name": "yingfung-solar-media"
+    }
+  ]
+}
+```
+
+- [ ] **Step 2: `package.json` 加 `r2:create`**
+
+喺 `"kv:create"` 之後加一行：
+
+```json
+    "kv:create": "wrangler kv namespace create CACHE",
+    "r2:create": "wrangler r2 bucket create yingfung-solar-media",
+```
+
+- [ ] **Step 3: `src/lib/env.ts` 加 `MEDIA`**
+
+`AppEnv` 改成：
+
+```ts
+export type AppEnv = {
+  DB: D1Database;
+  CACHE: KVNamespace;
+  MEDIA: R2Bucket;
+  ADMIN_PASSWORD?: string;
+  AI_API_KEY?: string;
+  TAVILY_API_KEY?: string;
+};
+```
+
+- [ ] **Step 4: `scripts/setup.mjs` 加建 R2 bucket 步驟**
+
+喺檔案上方 constant 區（`const KV_PLACEHOLDER = ...` 之後）加：
+
+```js
+const R2_BUCKET = "yingfung-solar-media";
+```
+
+喺 KV 區塊（`} else { console.log("KV id 已設定，略過。"); }`）之後、`const setPassword = await rl.question(...)` 之前加：
+
+```js
+  console.log(`檢查 / 建立 R2 bucket「${R2_BUCKET}」…`);
+  const r2List = runSoft("npx wrangler r2 bucket list");
+  const r2Text = `${r2List.out || ""}\n${r2List.err || ""}`;
+  if (new RegExp(`\\b${R2_BUCKET}\\b`).test(r2Text)) {
+    console.log("  R2 bucket 已存在，略過。");
+  } else {
+    const r2 = runSoft(`npx wrangler r2 bucket create ${R2_BUCKET}`);
+    if (r2.ok) {
+      console.log("  R2 bucket 已建立。");
+    } else {
+      console.log("  建立 R2 bucket 失敗（可能未開通 R2），請稍後手動執行： npm run r2:create");
+      console.log(r2.out || r2.err || "");
+    }
+  }
+```
+
+- [ ] **Step 5: 重新產生 binding 型別**
+
+Run: `npm run types`
+Expected: 成功，`worker-configuration.d.ts` 內 `MEDIA: R2Bucket;` 出現喺 `Env`。
+
+Run: `rg -n "MEDIA: R2Bucket" worker-configuration.d.ts`
+Expected: 有一行 match（若 `wrangler types` 讀唔到 R2 binding，手動加都唔會影響 build，但正常會出）。
+
+- [ ] **Step 6: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add wrangler.jsonc package.json scripts/setup.mjs src/lib/env.ts worker-configuration.d.ts
+git commit -m "Add R2 MEDIA binding and setup script"
+```
+
+---
+
+### Task 2: `src/lib/media.ts` 媒體工具
+
+**Files:**
+- Create: `src/lib/media.ts`
+
+- [ ] **Step 1: 建立 `src/lib/media.ts`**
+
+```ts
+import type { AppEnv } from "./env";
+
+export const MEDIA_PREFIX = "/media/";
+
+/** 由 R2 key 砌出對外 URL。 */
+export function mediaUrl(key: string): string {
+  return `${MEDIA_PREFIX}${key}`;
+}
+
+/** 由 /media/... URL 取出 R2 key；唔係 /media/ 開頭回 null。 */
+export function mediaKey(url: string | null | undefined): string | null {
+  if (!url || !url.startsWith(MEDIA_PREFIX)) return null;
+  return url.slice(MEDIA_PREFIX.length);
+}
+
+/** 刪除 /media/... 對應嘅 R2 物件；外部 URL 或空值唔理，唔會 throw。 */
+export async function deleteMedia(
+  env: AppEnv,
+  url: string | null | undefined,
+): Promise<void> {
+  const key = mediaKey(url);
+  if (!key) return;
+  try {
+    await env.MEDIA.delete(key);
+  } catch {
+    // 刪除失敗唔應該阻礙儲存流程。
+  }
+}
+```
+
+- [ ] **Step 2: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/lib/media.ts
+git commit -m "Add media helper for R2 keys and cleanup"
+```
+
+---
+
+### Task 3: 上傳同出圖 endpoints
+
+**Files:**
+- Create: `src/pages/admin/upload.ts`
+- Create: `src/pages/media/[...key].ts`
+
+- [ ] **Step 1: 建立 `src/pages/admin/upload.ts`**
+
+```ts
+import type { APIRoute } from "astro";
+import { getEnv } from "../../lib/env";
+import { mediaUrl } from "../../lib/media";
+
+export const prerender = false;
+
+const SCOPES = new Set(["settings", "cases", "posts"]);
+
+const ALLOWED: Record<string, string> = {
+  "image/webp": "webp",
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "image/gif": "gif",
+};
+
+const MAX_BYTES = 8 * 1024 * 1024;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+export const POST: APIRoute = async ({ request }) => {
+  let form: FormData;
+  try {
+    form = await request.formData();
+  } catch {
+    return json({ ok: false, error: "無法讀取上傳內容。" }, 400);
+  }
+
+  const file = form.get("file");
+  const scope = String(form.get("scope") ?? "");
+
+  if (!(file instanceof File) || file.size === 0) {
+    return json({ ok: false, error: "請揀選圖片檔案。" }, 400);
+  }
+  if (!SCOPES.has(scope)) {
+    return json({ ok: false, error: "上傳目標唔正確。" }, 400);
+  }
+  const ext = ALLOWED[file.type];
+  if (!ext) {
+    return json({ ok: false, error: "只支援 JPG / PNG / WebP / GIF 圖片。" }, 400);
+  }
+  if (file.size > MAX_BYTES) {
+    return json({ ok: false, error: "圖片太大（上限 8MB）。" }, 400);
+  }
+
+  const key = `${scope}/${crypto.randomUUID()}.${ext}`;
+  try {
+    await getEnv().MEDIA.put(key, await file.arrayBuffer(), {
+      httpMetadata: { contentType: file.type },
+    });
+  } catch {
+    return json({ ok: false, error: "上傳失敗，請稍後再試。" }, 500);
+  }
+
+  return json({ ok: true, url: mediaUrl(key) });
+};
+```
+
+- [ ] **Step 2: 建立 `src/pages/media/[...key].ts`**
+
+```ts
+import type { APIRoute } from "astro";
+import { getEnv } from "../../lib/env";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ params, request }) => {
+  const key = params.key ?? "";
+  if (!key) return new Response("Not found", { status: 404 });
+
+  const obj = await getEnv().MEDIA.get(key);
+  if (!obj) return new Response("Not found", { status: 404 });
+
+  const etag = obj.httpEtag;
+  if (etag && request.headers.get("if-none-match") === etag) {
+    return new Response(null, { status: 304, headers: { ETag: etag } });
+  }
+
+  const headers = new Headers();
+  headers.set("Content-Type", obj.httpMetadata?.contentType ?? "application/octet-stream");
+  headers.set("Cache-Control", "public, max-age=31536000, immutable");
+  if (etag) headers.set("ETag", etag);
+
+  return new Response(obj.body, { headers });
+};
+```
+
+- [ ] **Step 3: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error，而且 `dist/` 唔會 build 出 `/media` 靜態頁（endpoint 係 SSR）。
+
+- [ ] **Step 4: 手動測試 endpoints**
+
+Run: `npm run dev`（另一個 terminal）
+Expected:
+1. 開 `http://localhost:4321/media/nope.webp` → 404。
+2. 登入 `http://localhost:4321/admin` 後（需要 `.dev.vars` 有 `ADMIN_PASSWORD`），用瀏覽器 DevTools console 執行（本機 R2 係 wrangler 模擬）：
+
+```js
+const fd = new FormData();
+fd.append("file", new File([new Uint8Array([82,73,70,70])], "x.webp", { type: "image/webp" }));
+fd.append("scope", "cases");
+console.log(await (await fetch("/admin/upload", { method: "POST", body: fd })).json());
+```
+
+Expected: `{ ok: true, url: "/media/cases/<uuid>.webp" }`，跟住開嗰個 url 有 response（body 係嗰 4 bytes）。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/pages/admin/upload.ts "src/pages/media/[...key].ts"
+git commit -m "Add R2 upload and media serving endpoints"
+```
+
+---
+
+### Task 4: `ImageField` 元件同後台 client script
+
+**Files:**
+- Create: `src/components/admin/ImageField.astro`
+- Modify: `src/layouts/AdminLayout.astro`
+
+- [ ] **Step 1: 建立 `src/components/admin/ImageField.astro`**
+
+```astro
+---
+interface Props {
+  name: string;
+  label: string;
+  value?: string | null;
+  scope: "settings" | "cases" | "posts";
+  id?: string;
+}
+
+const { name, label, value = "", scope, id = name } = Astro.props;
+---
+
+<div class="image-field" data-image-field data-scope={scope}>
+  <label for={id}>{label}</label>
+  <input
+    id={id}
+    name={name}
+    type="text"
+    value={value ?? ""}
+    placeholder="https://... 或按下面上傳"
+    class="image-url"
+  />
+  <div class="image-actions">
+    <input type="file" accept="image/*" data-image-input />
+    <span class="image-status" data-image-status></span>
+  </div>
+  <img class="image-preview" data-image-preview src={value || undefined} alt="" hidden={!value} />
+</div>
+```
+
+- [ ] **Step 2: `AdminLayout.astro` 加 client script**
+
+喺 `</main>` 之後、`</body>` 之前加：
+
+```astro
+    <script>
+      const MAX_WIDTH = 1600;
+      const QUALITY = 0.85;
+
+      async function toOptimised(file: File): Promise<Blob> {
+        if (!("createImageBitmap" in window)) return file;
+        try {
+          const bitmap = await createImageBitmap(file);
+          const scale = Math.min(1, MAX_WIDTH / bitmap.width);
+          const width = Math.max(1, Math.round(bitmap.width * scale));
+          const height = Math.max(1, Math.round(bitmap.height * scale));
+          const canvas = document.createElement("canvas");
+          canvas.width = width;
+          canvas.height = height;
+          const ctx = canvas.getContext("2d");
+          if (!ctx) return file;
+          ctx.drawImage(bitmap, 0, 0, width, height);
+          if (typeof bitmap.close === "function") bitmap.close();
+          const blob = await new Promise<Blob | null>((resolve) =>
+            canvas.toBlob(resolve, "image/webp", QUALITY),
+          );
+          return blob ?? file;
+        } catch {
+          return file;
+        }
+      }
+
+      async function upload(field: HTMLElement, file: File): Promise<void> {
+        const scope = field.dataset.scope ?? "";
+        const input = field.querySelector<HTMLInputElement>(".image-url");
+        const preview = field.querySelector<HTMLImageElement>(".image-preview");
+        const status = field.querySelector<HTMLElement>(".image-status");
+        if (!input || !status) return;
+
+        status.textContent = "上傳中…";
+        const blob = await toOptimised(file);
+        const body = new FormData();
+        body.append("file", new File([blob], file.name, { type: blob.type }));
+        body.append("scope", scope);
+
+        try {
+          const res = await fetch("/admin/upload", { method: "POST", body });
+          const data = (await res.json()) as { ok: boolean; url?: string; error?: string };
+          if (!res.ok || !data.ok || !data.url) {
+            status.textContent = data.error ?? "上傳失敗。";
+            return;
+          }
+          input.value = data.url;
+          if (preview) {
+            preview.src = data.url;
+            preview.hidden = false;
+          }
+          status.textContent = "✓ 已上傳";
+        } catch {
+          status.textContent = "上傳失敗，請檢查網絡。";
+        }
+      }
+
+      document.querySelectorAll<HTMLElement>("[data-image-field]").forEach((field) => {
+        const fileInput = field.querySelector<HTMLInputElement>("[data-image-input]");
+        if (!fileInput) return;
+        fileInput.addEventListener("change", () => {
+          const file = fileInput.files?.[0];
+          if (file) void upload(field, file);
+        });
+      });
+    </script>
+```
+
+- [ ] **Step 3: `AdminLayout.astro` 加樣式**
+
+喺 `<style is:global>` 內 `.row { ... }` 之前加：
+
+```css
+  .image-field { display: block; }
+  .image-actions { display: flex; align-items: center; gap: 10px; margin-top: 8px; flex-wrap: wrap; }
+  .image-actions input[type="file"] { font: inherit; font-size: 13px; max-width: 100%; }
+  .image-status { font-size: 12.5px; font-weight: 600; color: #0b8a5e; }
+  .image-preview { display: block; margin-top: 10px; max-width: 220px; border-radius: 10px; }
+  .image-preview[hidden] { display: none; }
+```
+
+- [ ] **Step 4: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/components/admin/ImageField.astro src/layouts/AdminLayout.astro
+git commit -m "Add ImageField component and client-side upload script"
+```
+
+---
+
+### Task 5: 網站設定圖片欄位（含換圖刪舊）
+
+**Files:**
+- Modify: `src/data/settings-fields.ts`
+- Modify: `src/pages/admin/settings.astro`
+
+- [ ] **Step 1: `settings-fields.ts` 加 `image` 型別**
+
+將第一行改成：
+
+```ts
+export type FieldType = "text" | "textarea" | "url" | "image";
+```
+
+將 `hero_image` 同 `og_image` 兩行改成：
+
+```ts
+      { key: "hero_image", label: "主視覺圖片", type: "image" },
+```
+
+```ts
+      { key: "og_image", label: "分享圖片 (OG image)", type: "image" },
+```
+
+- [ ] **Step 2: `settings.astro` 加 import 同刪舊邏輯**
+
+將 frontmatter 改成：
+
+```astro
+---
+import AdminLayout from "../../layouts/AdminLayout.astro";
+import ImageField from "../../components/admin/ImageField.astro";
+import { ALL_SETTING_KEYS, SETTINGS_GROUPS } from "../../data/settings-fields";
+import { siteSettings } from "../../db/schema";
+import { getSettings } from "../../data/content";
+import { getDb } from "../../lib/db";
+import { getEnv } from "../../lib/env";
+import { parseForm } from "../../lib/form";
+import { deleteMedia } from "../../lib/media";
+import { settingsInput } from "../../schemas";
+
+export const prerender = false;
+
+const env = getEnv();
+const db = getDb(env.DB);
+
+const IMAGE_SETTING_KEYS = new Set(
+  SETTINGS_GROUPS.flatMap((g) =>
+    g.fields.filter((f) => f.type === "image").map((f) => f.key),
+  ),
+);
+
+let saved = false;
+let error = "";
+
+if (Astro.request.method === "POST") {
+  const form = await Astro.request.formData();
+  const parsed = parseForm(form, settingsInput);
+  if (!parsed.ok) {
+    error = Object.values(parsed.errors)[0] ?? "設定有誤。";
+  } else {
+    const before = await getSettings(db);
+    const now = new Date();
+    const submitted = new Set(
+      [...form.keys()].filter((k) => ALL_SETTING_KEYS.includes(k)),
+    );
+    for (const key of ALL_SETTING_KEYS) {
+      if (!submitted.has(key)) continue;
+      const value = String((parsed.data as Record<string, unknown>)[key] ?? "");
+      if (IMAGE_SETTING_KEYS.has(key) && before[key] !== value) {
+        await deleteMedia(env, before[key]);
+      }
+      await db
+        .insert(siteSettings)
+        .values({ key, value, updatedAt: now })
+        .onConflictDoUpdate({ target: siteSettings.key, set: { value, updatedAt: now } });
+    }
+    saved = true;
+  }
+}
+
+const settings = await getSettings(db);
+---
+```
+
+- [ ] **Step 3: `settings.astro` 欄位 render 加 ImageField**
+
+將 template 內 `SETTINGS_GROUPS.map((group) => ( ... ))` 的欄位 map 改成（其餘不變）：
+
+```astro
+            {group.fields.map((f) => (
+              <div style={f.type === "textarea" ? "grid-column:1/-1" : ""}>
+                {f.type === "image" ? (
+                  <ImageField
+                    name={f.key}
+                    label={f.label}
+                    value={settings[f.key] ?? ""}
+                    scope="settings"
+                    id={f.key}
+                  />
+                ) : (
+                  <>
+                    <label for={f.key}>{f.label}</label>
+                    {f.type === "textarea" ? (
+                      <textarea id={f.key} name={f.key} placeholder={f.placeholder}>
+                        {settings[f.key] ?? ""}
+                      </textarea>
+                    ) : (
+                      <input
+                        id={f.key}
+                        name={f.key}
+                        type="text"
+                        value={settings[f.key] ?? ""}
+                        placeholder={f.placeholder}
+                      />
+                    )}
+                  </>
+                )}
+              </div>
+            ))}
+```
+
+- [ ] **Step 4: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 5: 手動測試**
+
+Run: `npm run dev`
+Expected: `/admin/settings` 的「首頁 Hero」同「SEO 設定」入面，主視覺圖片同 OG 圖變咗有檔案選擇 + 預覽；上傳後 URL 欄填 `/media/settings/<uuid>.webp`；儲存後前台首頁圖片更新；再換一張，舊 `/media/...` 變 404。
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/data/settings-fields.ts src/pages/admin/settings.astro
+git commit -m "Add image upload to site settings with old-file cleanup"
+```
+
+---
+
+### Task 6: 完成案例圖片上傳
+
+**Files:**
+- Modify: `src/pages/admin/cases.astro`
+
+- [ ] **Step 1: 加 import 同 `env`**
+
+喺 import 區加：
+
+```astro
+import ImageField from "../../components/admin/ImageField.astro";
+import { deleteMedia } from "../../lib/media";
+```
+
+將 `const db = getDb(getEnv().DB);` 改成：
+
+```astro
+const env = getEnv();
+const db = getDb(env.DB);
+```
+
+- [ ] **Step 2: save 時比對並刪舊圖**
+
+將 `if (action === "add" || action === "save")` 內嘅 `} else {`（更新分支）改成：
+
+```astro
+    } else {
+      const id = str(form, "id");
+      const newImage = parsed.data.imageUrl || null;
+      const [current] = await db.select().from(cases).where(eq(cases.id, id)).limit(1);
+      if (current && current.imageUrl !== newImage) {
+        await deleteMedia(env, current.imageUrl);
+      }
+      await db
+        .update(cases)
+        .set({
+          title: parsed.data.title,
+          location: parsed.data.location || null,
+          completedAt: parsed.data.completedAt || null,
+          description: parsed.data.description || null,
+          imageUrl: newImage,
+          status: parsed.data.status,
+          updatedAt: new Date(),
+        })
+        .where(eq(cases.id, id));
+    }
+```
+
+- [ ] **Step 3: delete 時刪圖**
+
+將 `} else if (action === "delete") { ... }` 改成：
+
+```astro
+  } else if (action === "delete") {
+    const id = str(form, "id");
+    const [current] = await db.select().from(cases).where(eq(cases.id, id)).limit(1);
+    await deleteMedia(env, current?.imageUrl);
+    await db.delete(cases).where(eq(cases.id, id));
+  }
+```
+
+- [ ] **Step 4: 新增表單改用 ImageField**
+
+將新增表單內：
+
+```astro
+        <div>
+          <label for="a-img">圖片 URL</label>
+          <input id="a-img" name="imageUrl" type="text" placeholder="https://..." />
+        </div>
+```
+
+改成：
+
+```astro
+        <div>
+          <ImageField name="imageUrl" label="圖片" scope="cases" id="a-img" />
+        </div>
+```
+
+- [ ] **Step 5: 每張卡改用 ImageField 並移除舊預覽**
+
+將每張卡內：
+
+```astro
+              <div>
+                <label>圖片 URL</label>
+                <input name="imageUrl" type="text" value={item.imageUrl ?? ""} />
+              </div>
+```
+
+改成：
+
+```astro
+              <div>
+                <ImageField
+                  name="imageUrl"
+                  label="圖片"
+                  scope="cases"
+                  value={item.imageUrl}
+                  id={`img-${item.id}`}
+                />
+              </div>
+```
+
+再移除舊嘅 standalone 預覽 block（ImageField 已自帶預覽）：
+
+```astro
+            {item.imageUrl && (
+              <img src={item.imageUrl} alt={item.title} style="margin-top:14px;max-width:220px;border-radius:10px;" />
+            )}
+```
+
+- [ ] **Step 6: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 7: 手動測試**
+
+Run: `npm run dev`
+Expected: `/admin/cases` 新增同每張卡都有上傳；上傳後前台「完成案例」顯示新圖；換圖後舊圖 404；刪除案例後其圖 404。
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/pages/admin/cases.astro
+git commit -m "Add image upload to cases with cleanup"
+```
+
+---
+
+### Task 7: 文章封面上傳
+
+**Files:**
+- Modify: `src/pages/admin/post/[id].astro`
+
+- [ ] **Step 1: 加 import 同 `env`**
+
+喺 import 區加：
+
+```astro
+import ImageField from "../../../components/admin/ImageField.astro";
+import { deleteMedia } from "../../../lib/media";
+```
+
+將 `const db = getDb(getEnv().DB);` 改成：
+
+```astro
+const env = getEnv();
+const db = getDb(env.DB);
+```
+
+- [ ] **Step 2: 刪文時刪封面**
+
+將：
+
+```astro
+  if (action === "delete" && !isNew) {
+    await db.delete(posts).where(eq(posts.id, id!));
+    return Astro.redirect("/admin");
+  }
+```
+
+改成：
+
+```astro
+  if (action === "delete" && !isNew) {
+    await deleteMedia(env, existing?.coverImage);
+    await db.delete(posts).where(eq(posts.id, id!));
+    return Astro.redirect("/admin");
+  }
+```
+
+- [ ] **Step 3: 更新時比對並刪舊封面**
+
+喺 `} else {`（更新分支）內、`await db.update(posts)` 之前加：
+
+```astro
+      if (existing!.coverImage !== coverImage) {
+        await deleteMedia(env, existing!.coverImage);
+      }
+```
+
+更新分支開頭應該係：
+
+```astro
+    } else {
+      if (existing!.coverImage !== coverImage) {
+        await deleteMedia(env, existing!.coverImage);
+      }
+      await db
+        .update(posts)
+        .set({
+          slug,
+          ...
+```
+
+- [ ] **Step 4: 封面欄改用 ImageField**
+
+將：
+
+```astro
+    <label for="coverImage">封面圖片 URL（列表卡片用）</label>
+    {errors.coverImage && <span class="field-error">{errors.coverImage}</span>}
+    <input
+      id="coverImage"
+      name="coverImage"
+      type="text"
+      value={post.coverImage ?? ""}
+      placeholder="https://..."
+    />
+```
+
+改成：
+
+```astro
+    {errors.coverImage && <span class="field-error">{errors.coverImage}</span>}
+    <ImageField
+      name="coverImage"
+      label="封面圖片（列表卡片用）"
+      scope="posts"
+      value={post.coverImage}
+      id="coverImage"
+    />
+```
+
+- [ ] **Step 5: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 6: 手動測試**
+
+Run: `npm run dev`
+Expected: `/admin/post/new` 同上傳封面；發布後 Blog 列表／文章頁顯示新封面；換封面舊圖 404；刪文封面 404。
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add "src/pages/admin/post/[id].astro"
+git commit -m "Add cover image upload to blog posts with cleanup"
+```
+
+---
+
+### Task 8: DOX 文件更新
+
+**Files:**
+- Modify: `src/AGENTS.md`
+- Modify: `src/lib/AGENTS.md`
+- Modify: `src/data/AGENTS.md`
+- Modify: `AGENTS.md`
+
+- [ ] **Step 1: 更新 `src/AGENTS.md`**
+
+Admin 段「- **圖片**：一律以 URL 字串處理（暫無上傳）。」改成：
+
+```markdown
+- **圖片**：圖片欄位（settings 的 `hero_image` / `og_image`、`cases.imageUrl`、`posts.coverImage`）用 `components/admin/ImageField.astro`，可揀檔即時上傳去 R2（binding `MEDIA`），亦可貼 URL；client 端縮到最大寬 1600px 並轉 WebP 先上傳。上傳 endpoint `/admin/upload`（受 middleware 保護），出圖 endpoint `/media/[...key]`（公開、`immutable` cache）。換圖／刪除時由 `lib/media.ts` 的 `deleteMedia` 清舊 R2 檔。
+```
+
+喺 Routes & SSR 段「**Endpoint**」bullet 之後加：
+
+```markdown
+- **圖片 endpoints**：`/admin/upload`（POST，上傳去 R2 `MEDIA`）；`/media/[...key]`（GET，讀 R2 出圖，設 `Cache-Control: public, max-age=31536000, immutable` 同 ETag／304）。
+```
+
+- [ ] **Step 2: 更新 `src/lib/AGENTS.md`**
+
+Ownership 段改成「擁有 `src/lib/` 七個檔案：`env.ts`、`db.ts`、`auth.ts`、`form.ts`、`media.ts`、`ai.ts`、`markdown.ts`。」
+
+`env.ts` bullet 的 `AppEnv` 清單加 `MEDIA`（`AppEnv`（`DB`、`CACHE`、`MEDIA`、`ADMIN_PASSWORD?`…））。
+
+喺 `markdown.ts` bullet 之前加：
+
+```markdown
+- **`media.ts`**：`MEDIA_PREFIX`（`/media/`）、`mediaUrl(key)`、`mediaKey(url)`、`deleteMedia(env, url)`。`deleteMedia` 只處理 `/media/` 開頭嘅值，外部 URL／空值唔理、唔 throw。
+```
+
+- [ ] **Step 3: 更新 `src/data/AGENTS.md`**
+
+`settings-fields.ts` 相關：Local Contracts 內「**設定欄位**」bullet 補一句：
+
+```markdown
+- **圖片欄位**：`FieldType` 有 `"image"`；`hero_image` / `og_image` 用呢個型別，`/admin/settings` 會 render `ImageField`（可上傳去 R2）。
+```
+
+- [ ] **Step 4: 更新根 `AGENTS.md`**
+
+「關鍵慣例與陷阱」內補一條（放喺環境變數 / 資料層附近）：
+
+```markdown
+- **圖片上傳**：圖片存 Cloudflare R2（binding `MEDIA`、bucket `yingfung-solar-media`），由同一個 Worker 的 `/media/*` 出圖；上傳經 `/admin/upload`，client 端先縮圖轉 WebP。本機靠 `platformProxy` 模擬 R2，雲端要先 `npm run r2:create`。圖片欄位仍可貼 URL；換圖／刪除時 `lib/media.ts` 會清舊 R2 檔。
+```
+
+`scripts/` 是 project-level files owned by root，唔使另加 Child DOX。
+
+- [ ] **Step 5: Build 驗證**
+
+Run: `npm run build`
+Expected: 完成，冇 error。
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add AGENTS.md src/AGENTS.md src/lib/AGENTS.md src/data/AGENTS.md
+git commit -m "Update DOX docs for R2 image upload"
+```
+
+---
+
+### Task 9: 最終端到端驗證
+
+**Files:** 無（只驗證）
+
+- [ ] **Step 1: 全量 build**
+
+Run: `npm run build`
+Expected: 成功。
+
+- [ ] **Step 2: 端到端手動檢查（`npm run dev`）**
+
+逐項確認：
+
+1. `/admin/settings`：`hero_image`、`og_image` 可上傳 + 預覽；儲存後前台首頁主視覺／`<meta property="og:image">` 用新圖（OG 應係絕對 URL）。
+2. `/admin/cases`：新增／編輯案例可上傳；前台「完成案例」顯示新圖。
+3. `/admin/post/new` 同既有文章：封面可上傳；Blog 列表／文章頁顯示新封面。
+4. 亂打 `/media/xxx` → 404；正常 `/media/<key>` 有 response 同 `Cache-Control: immutable`。
+5. 換圖後，舊 `/media/<key>` → 404。
+6. 貼外部 URL（唔上傳）→ 照樣儲存同顯示。
+7. 上傳 SVG 或 >8MB 檔 → 顯示中文錯誤、唔會寫入。
+8. 冇 JS（停用 JavaScript）→ URL 欄仍可手動貼，主表單可儲存。
+
+- [ ] **Step 3: 確認 git 狀態乾淨**
+
+Run: `git status --short`
+Expected: 冇未 commit 嘅改動（或只有預期內嘅檔案）。
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- 4 個欄位全部支援 → Task 5（settings 2 個）、Task 6（cases）、Task 7（post）。
+- Worker `/media/*` 出圖 → Task 3。
+- 瀏覽器端縮圖轉 WebP → Task 4。
+- 保留貼 URL → Task 4（ImageField 保留 text input）＋ Task 9 step 2.8。
+- 自動刪舊圖 → Task 2 `deleteMedia`、Task 5/6/7 呼叫。
+- 拒絕 SVG / 8MB 上限 → Task 3。
+- R2 binding / env / setup / r2:create → Task 1。
+- 冇 UI migration → 冇 DB task，正確。
+- DOX 更新 → Task 8。
+
+**Placeholder scan:** 冇 TBD／「add appropriate…」；每個 code step 都有完整內容。
+
+**Type consistency:** `deleteMedia(env, url)`、`mediaUrl(key)`、`mediaKey(url)`、`ImageField` props（`name` / `label` / `value` / `scope` / `id`）喺所有 task 一致；`scope` 值只用 `settings` / `cases` / `posts`，同 endpoint `SCOPES` 一致。