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

docs: record R2 MEDIA binding in AGENTS.md

Browse Source
This commit is contained in:
philip-cat
2026-09-12 09:54:53 +08:00
parent 125030ce2e
commit 002cf368c3
2 changed files with 5 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+4 -3
View File
@@ -1,6 +1,6 @@
# AGENTS.md # 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 - `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` - 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 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` 是唯一可跑的驗證。 - 沒有 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 匯出。 - **表單驗證集中在 `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`（會覆蓋後台設定）。 - **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`（雲端）。 - **部署用 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`）。 - **上線前要改 `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。 - **後台認證**：`src/middleware.ts` 保護所有 `/admin`，用 HMAC-signed cookie（`src/lib/auth.ts`）；未設 `ADMIN_PASSWORD`（本機在 `.dev.vars`，已 gitignore）會回 503。
- **Chakra v3 + Emotion**：前台 React 元件要用 `Provider` / `SiteChrome`（內含 `<ChakraProvider value={system}>`），theme 在 `src/theme/system.ts`。Astro 以 `client:load` 掛 island。 - **Chakra v3 + Emotion**：前台 React 元件要用 `Provider` / `SiteChrome`（內含 `<ChakraProvider value={system}>`），theme 在 `src/theme/system.ts`。Astro 以 `client:load` 掛 island。
src/lib/AGENTS.md
+1 -1
View File
@@ -11,7 +11,7 @@
## Local Contracts ## 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`。 - **`db.ts`**：`getDb(env.DB)` → Drizzle，並 re-export `schema`。
- **`auth.ts`**：HMAC-SHA256 signed cookie 認證。 - **`auth.ts`**：HMAC-SHA256 signed cookie 認證。
- 匯出 `SESSION_COOKIE`、`checkPassword`、`createSession`、`verifySession`、`sessionCookieOptions`。 - 匯出 `SESSION_COOKIE`、`checkPassword`、`createSession`、`verifySession`、`sessionCookieOptions`。