first commit

src/AGENTS.md

@@ -0,0 +1,69 @@
+# src/AGENTS.md
+
+## Purpose
+
+`src/` 係全疊應用程式碼：Astro 路由、React/Chakra 前台 UI、D1/Drizzle 資料層、基礎工具，以及 theme 同 layout。
+
+## Ownership
+
+- 擁有 `src/` 全層，亦直接擁有以下冇獨立 child doc 的部分：
+  - `theme/system.ts` — Chakra system（tokens / semanticTokens / fonts / globalCss），前台顏色同字體的唯一來源。現行設計：editorial 極簡風（暖米白 `#FAF8F4` 底、琥珀金 `brand` accent、墨黑 `ink`、Noto Serif HK 標題），詳見 `docs/superpowers/specs/2026-09-11-editorial-redesign-design.md`。
+  - `layouts/Base.astro` — 前台 SEO head（canonical / OG / Twitter / sitemap link）＋ Noto Sans HK。
+  - `layouts/AdminLayout.astro` — 後台外框，純 CSS、與前台一致的色系。
+  - `config.ts` — build-time 靜態頁用的 `SITE_NAME` / `SITE_TAGLINE`（可管理內容一律放 D1，唔放呢度）。
+  - `middleware.ts` — 保護 `/admin`：設 `locals.isAdmin`，無 `ADMIN_PASSWORD` 回 503，未登入導向 `/admin/login`。
+  - `env.d.ts` — `App.Locals.isAdmin` 型別宣告。
+  - `pages/` — 路由層同 `/admin` 後台（詳見下面 Routes & SSR / Admin，因 Astro 限制冇獨立 child doc）。
+
+## Local Contracts
+
+- **架構**：Astro 7（`output: "static"` + per-page SSR）+ `@astrojs/react` + Chakra UI v3（Emotion），單一 Cloudflare Worker。
+- **環境變數**：一律 `getEnv()`（`src/lib/env.ts`）。Astro v6 起已移除 `Astro.locals.runtime.env`。
+- **資料流**：`.astro` 頁面 → `getDb(getEnv().DB)` → `src/data/content.ts` 查詢 → props 傳畀 React island。元件唔直接讀 DB。
+- **語言**：所有 UI 文案、註解、後台文案都係繁體中文（廣東話），網站唔做雙語。
+- **產生檔唔好手改**：`dist/`、`.astro/`、`.wrangler/`、`worker-configuration.d.ts`。
+
+### 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`。
+  - 保持靜態：`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`。
+- **SEO**：用 `Base.astro`；canonical / OG / sitemap 全部靠 `astro.config.mjs` 的 `site`（現為佔位 `https://example.com`，上線前要改）。
+
+### Admin（`pages/admin/`）
+
+- 所有 `/admin` 路由**必須** `export const prerender = false`。
+- **認證**由 `middleware.ts` 統一處理；登入喺 `admin/login.astro`（`checkPassword` + `createSession`），登出喺 `logout.ts`。
+- **UI**：全部用 `AdminLayout.astro`，純 Astro SSR 表單（`POST` + `formData`），**唔引入** React / Chakra。
+- **流程**：每個 POST 處理完 `Astro.redirect` 返對應列表頁。
+- **通用動作**：`add` / `save` / `delete` / `up` / `down`（排序以交換 `sortOrder` 實作）。
+- **通用內容編輯器**：`content/[kind].astro`，`kind ∈ service | feature | step | faq`（見 `db/schema.ts` 的 `CONTENT_KINDS`），欄位標籤由檔案內 `META` 定義。
+- **網站設定**：`settings.astro` 用 `data/settings-fields.ts` 的 `SETTINGS_GROUPS` / `ALL_SETTING_KEYS` 產生表單，逐 key upsert。
+- **文章**：`index.astro` 列表、`post/[id].astro` 新增／編輯（`id === "new"` 為新增）；slug 自動 `slugify` 並用 `uniqueSlug` 去重。
+- **圖片**：一律以 URL 字串處理（暫無上傳）。
+- 前台可見性靠 `status`（`published` / `draft`）；列表頁顯示全部，前台只顯示 published。
+
+## Work Guidance
+
+- 改前台視覺先睇 `theme/system.ts` 的 tokens，優先重用語意 token，唔好散落硬編色值。
+- 新增 endpoint 或 SSR 頁後，確認 `prerender = false` 同相應快取 header 都有。
+- 新增一個內容欄位：先改 `db/schema.ts` → `npm run db:generate`，再改對應 admin 表單同 `data/content.ts`。
+- **唔好喺 `src/pages/` 放 `.md` 文件**（例如 AGENTS.md）：Astro 會將佢變成公開路由（今次已實測 `/AGENTS`、`/admin/AGENTS`）。Astro 只支援用 `_` 前綴豁免，但同 DOX 的 `AGENTS.md` 命名衝突，所以 `pages/` 的合約一律寫喺本文件。其餘 `src/` 子目錄的 `AGENTS.md`（data/db/lib/components）唔會被路由。
+
+## Verification
+
+- `npm run build`（唯一的 build/type 驗證；冇 test/lint/typecheck script）。
+- `npm run dev`（:4321）目測前台／Blog／後台；測 `/blog/[slug]` 404、登入／登出流程。
+
+## Child DOX Index
+
+| Path | Scope |
+|---|---|
+| `components/site/AGENTS.md` | 前台 React island 與 Chakra UI 元件 |
+| `data/AGENTS.md` | D1 讀取查詢層與後台設定欄位定義 |
+| `db/AGENTS.md` | Drizzle schema（migration 的唯一來源） |
+| `lib/AGENTS.md` | auth / env / db / markdown 基礎工具 |