philip-cat/yingfungsolar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document media upload/serving endpoints in src/AGENTS.md

Browse Source
This commit is contained in:
philip-cat
2026-09-12 09:58:40 +08:00
parent 8d1ffa9ab5
commit e18c3306d4
1 changed files with 3 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/AGENTS.md
+3 -3
View File
@@ -27,12 +27,12 @@
### Routes & SSR（`pages/`） ### Routes & SSR（`pages/`）
- **預設靜態**：`astro.config.mjs` 係 `output: "static"`。要讀 D1 或 request-time 資料的頁面／endpoint 必須在檔案內寫 `export const prerender = false`。 - **預設靜態**：`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`。 - 保持靜態：`about.astro`、`robots.txt.ts`。
- **環境變數**：只用 `getEnv()`，且只可喺 `prerender = false` 的頁面／endpoint 用。 - **環境變數**：只用 `getEnv()`，且只可喺 `prerender = false` 的頁面／endpoint 用。
- **前台動態頁**：讀 D1 → 傳 props 畀單一 React island（`client:load`），並設邊緣快取 `Cache-Control: public, s-maxage=60, stale-while-revalidate=300`。 - **前台動態頁**：讀 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 頁。 - **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`，唔使改現有流程。 - **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`，上線前要改）。 - **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。 - **網站設定**：`settings.astro` 用 `data/settings-fields.ts` 的 `SETTINGS_GROUPS` / `ALL_SETTING_KEYS` 產生表單，逐 key upsert。
- **文章**：`index.astro` 列表、`post/[id].astro` 新增／編輯（`id === "new"` 為新增）；slug 自動 `slugify` 並用 `uniqueSlug` 去重。 - **文章**：`index.astro` 列表、`post/[id].astro` 新增／編輯（`id === "new"` 為新增）；slug 自動 `slugify` 並用 `uniqueSlug` 去重。
- **AI 生成**：`ai.astro`（`/admin/ai`）管 AI 設定 + 關鍵字佇列，同步呼叫 `generateBlogPost`；成功會 redirect 去新草稿 `/admin/post/<id>`。生成按鈕用 inline `onsubmit` 顯示「生成中…」。 - **AI 生成**：`ai.astro`（`/admin/ai`）管 AI 設定 + 關鍵字佇列，同步呼叫 `generateBlogPost`；成功會 redirect 去新草稿 `/admin/post/<id>`。生成按鈕用 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。 - 前台可見性靠 `status`（`published` / `draft`）；列表頁顯示全部，前台只顯示 published。
## Work Guidance ## Work Guidance