From 002cf368c36cdd5302a3f7147cff032d9b6ec2c8 Mon Sep 17 00:00:00 2001 From: philipcheung Date: Sat, 12 Sep 2026 09:54:53 +0800 Subject: [PATCH] docs: record R2 MEDIA binding in AGENTS.md --- AGENTS.md | 7 ++++--- src/lib/AGENTS.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b604dd..6dd2710 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -Astro 7 + React 19 + Chakra UI v3，部署在 Cloudflare Workers（單一 Worker）+ D1 + Drizzle。一頁式官網 + Blog + `/admin` 後台。 +Astro 7 + React 19 + Chakra UI v3，部署在 Cloudflare Workers（單一 Worker）+ D1 + KV + R2 + Drizzle。一頁式官網 + Blog + `/admin` 後台。 ## 指令 @@ -9,7 +9,8 @@ Astro 7 + React 19 + Chakra UI v3，部署在 Cloudflare Workers（單一 Worker - `npm run preview` / `npm run deploy` — build 後用 wrangler dev / deploy - DB（本機用 `:local`，雲端省略）：`npm run db:generate` → `db:migrate:local` / `db:migrate` → `db:seed:local` / `db:seed` - `npm run types` — 重新產生 `worker-configuration.d.ts`；`npm run secret` — 設定 `ADMIN_PASSWORD` -- `npm run setup` — 一鍵 Cloudflare provision（建 D1 / KV、寫 `wrangler.jsonc`、設 secret、可選套 migration + seed） +- R2：`npm run r2:create` — 建立媒體 bucket `yingfung-solar-media`（binding `MEDIA`） +- `npm run setup` — 一鍵 Cloudflare provision（建 D1 / KV / R2、寫 `wrangler.jsonc`、設 secret、可選套 migration + seed） - 沒有 test / lint / typecheck script（未安裝 @astrojs/check）。`npm run build` 是唯一可跑的驗證。 ## 關鍵慣例與陷阱 @@ -21,7 +22,7 @@ Astro 7 + React 19 + Chakra UI v3，部署在 Cloudflare Workers（單一 Worker - **表單驗證集中在 `src/schemas/`**（Zod）＋ `src/lib/form.ts` 的 `parseForm(form, schema)`：admin 頁面唔好再手寫逐欄驗證。實體輸入型別用 `z.infer` 由 schemas 匯出。 - **AI Blog**：`src/lib/ai.ts`（OpenAI 相容 chat completions + Tavily）＋ `/admin/ai`；**預設供應商 DeepSeek 官方（`https://api.deepseek.com`、`deepseek-flash`）**，提示詞通用唔綁行業（角色／公司資料由後台 `ai_context_prompt`／`ai_business_context` 提供）。同步生成、一律存草稿並標記關鍵字 `generated`。需要 secrets `AI_API_KEY`（必需）／`TAVILY_API_KEY`（可選）；未設時回明確錯誤，唔會 throw。已部署 DB 轉供應商要喺 `/admin/ai` 改，唔好重跑 `db:seed`（會覆蓋後台設定）。 - **部署用 Cloudflare Workers Builds**（Git push 自動）：build `npm run build`、deploy `npx wrangler deploy`。**Migration 唔會喺 CI 執行**，改 schema 要手動 `npm run db:migrate`（雲端）。 -- **`wrangler.jsonc` 有佔位 id**：`database_id` / KV `id` 要先用 `db:create` / `kv:create` 產生再貼上，未貼前無法部署。 +- **`wrangler.jsonc` 有佔位 id**：`database_id` / KV `id` 要先用 `db:create` / `kv:create` 產生再貼上，未貼前無法部署。R2 bucket 唔使貼 id，用 `r2:create`（或 `npm run setup`）建立即可，binding 係 `MEDIA`。 - **上線前要改 `astro.config.mjs` 的 `site`**：sitemap / canonical / OG 全部靠它（現為 `https://example.com`）。 - **後台認證**：`src/middleware.ts` 保護所有 `/admin`，用 HMAC-signed cookie（`src/lib/auth.ts`）；未設 `ADMIN_PASSWORD`（本機在 `.dev.vars`，已 gitignore）會回 503。 - **Chakra v3 + Emotion**：前台 React 元件要用 `Provider` / `SiteChrome`（內含 ``），theme 在 `src/theme/system.ts`。Astro 以 `client:load` 掛 island。 diff --git a/src/lib/AGENTS.md b/src/lib/AGENTS.md index cff8ccc..b5eef2c 100644 --- a/src/lib/AGENTS.md +++ b/src/lib/AGENTS.md @@ -11,7 +11,7 @@ ## Local Contracts -- **`env.ts`**：`getEnv()` 讀 `cloudflare:workers` 的 `env`，回 `AppEnv`（`DB`、`CACHE`、`ADMIN_PASSWORD?`、`AI_API_KEY?`、`TAVILY_API_KEY?`）。只能喺 `prerender = false` 的頁面／endpoint 用。**唔用** `Astro.locals.runtime.env`（Astro v6 起已移除）。 +- **`env.ts`**：`getEnv()` 讀 `cloudflare:workers` 的 `env`，回 `AppEnv`（`DB`、`CACHE`、`MEDIA`（R2Bucket）、`ADMIN_PASSWORD?`、`AI_API_KEY?`、`TAVILY_API_KEY?`）。只能喺 `prerender = false` 的頁面／endpoint 用。**唔用** `Astro.locals.runtime.env`（Astro v6 起已移除）。 - **`db.ts`**：`getDb(env.DB)` → Drizzle，並 re-export `schema`。 - **`auth.ts`**：HMAC-SHA256 signed cookie 認證。 - 匯出 `SESSION_COOKIE`、`checkPassword`、`createSession`、`verifySession`、`sessionCookieOptions`。