From e18c3306d4105fcd00e02c6c9e071f5c53230912 Mon Sep 17 00:00:00 2001 From: philipcheung Date: Sat, 12 Sep 2026 09:58:40 +0800 Subject: [PATCH] docs: document media upload/serving endpoints in src/AGENTS.md --- src/AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/AGENTS.md b/src/AGENTS.md index f3c2789..cc1e791 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -27,12 +27,12 @@ ### Routes & SSR（`pages/`） - **預設靜態**：`astro.config.mjs` 係 `output: "static"`。要讀 D1 或 request-time 資料的頁面／endpoint 必須在檔案內寫 `export const prerender = false`。 - - 目前 SSR：`index.astro`、`blog/index.astro`、`blog/[slug].astro`、`admin/**`、`sitemap.xml.ts`。 + - 目前 SSR：`index.astro`、`blog/index.astro`、`blog/[slug].astro`、`admin/**`、`media/[...key].ts`、`sitemap.xml.ts`。 - 保持靜態：`about.astro`、`robots.txt.ts`。 - **環境變數**：只用 `getEnv()`，且只可喺 `prerender = false` 的頁面／endpoint 用。 - **前台動態頁**：讀 D1 → 傳 props 畀單一 React island（`client:load`），並設邊緣快取 `Cache-Control: public, s-maxage=60, stale-while-revalidate=300`。 - **404**：`blog/[slug].astro` 找唔到文章 → 設 `Astro.response.status = 404` 並 render noindex 頁。 -- **Endpoint**：用 `APIRoute`；`sitemap.xml.ts` 由 D1 讀已發布文章並設 `s-maxage=3600`。 +- **Endpoint**：用 `APIRoute`；`sitemap.xml.ts` 由 D1 讀已發布文章並設 `s-maxage=3600`；`media/[...key].ts` 由 R2 讀圖並回 `public, max-age=31536000, immutable`（+ ETag / 304）。 - **AI 生成（同步）**：`/admin/ai` 的生成喺 admin POST 內同步 `await` 完成先 redirect。如日後要改做背景處理，可用 `Astro.locals.cfContext`（Cloudflare `ExecutionContext`）嘅 `waitUntil`，唔使改現有流程。 - **SEO**：用 `Base.astro`；canonical / OG / sitemap 全部靠 `astro.config.mjs` 的 `site`（現為佔位 `https://example.com`，上線前要改）。 @@ -48,7 +48,7 @@ - **網站設定**：`settings.astro` 用 `data/settings-fields.ts` 的 `SETTINGS_GROUPS` / `ALL_SETTING_KEYS` 產生表單，逐 key upsert。 - **文章**：`index.astro` 列表、`post/[id].astro` 新增／編輯（`id === "new"` 為新增）；slug 自動 `slugify` 並用 `uniqueSlug` 去重。 - **AI 生成**：`ai.astro`（`/admin/ai`）管 AI 設定 + 關鍵字佇列，同步呼叫 `generateBlogPost`；成功會 redirect 去新草稿 `/admin/post/`。生成按鈕用 inline `onsubmit` 顯示「生成中…」。 -- **圖片**：一律以 URL 字串處理（暫無上傳）。 +- **圖片**：一律以 URL 字串處理。上傳經 `admin/upload.ts`（`POST`，`scope ∈ settings | cases | posts`，JPG/PNG/WebP/GIF、上限 8MB，存 R2 `MEDIA`，回 `{ ok, url }`）；對外由公開 `media/[...key].ts` 服務。 - 前台可見性靠 `status`（`published` / `draft`）；列表頁顯示全部，前台只顯示 published。 ## Work Guidance