yingfungsolar/AGENTS.md

# AGENTS.md

Astro 7 + React 19 + Chakra UI v3，部署在 Cloudflare Workers（單一 Worker）+ D1 + KV + R2 + Drizzle。一頁式官網 + Blog + `/admin` 後台。

## 指令

- `npm run dev` — Astro dev（:4321，經 wrangler platformProxy 讀 `wrangler.jsonc` bindings）
- `npm run build` — `astro build`（唯一的驗證步驟）
- `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`
- 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` 是唯一可跑的驗證。

## 關鍵慣例與陷阱

- **SSR 頁面必須自己聲明**：`astro.config.mjs` 是 `output: "static"`，所有要讀 D1 的動態頁面都靠檔案內 `export const prerender = false`（首頁、blog、admin、sitemap.xml）。新增需要 request-time 資料的頁面時一定要加。
- **環境變數只用 `getEnv()`**（`src/lib/env.ts`，底層 `cloudflare:workers` 的 `env`）。Astro v6 起已移除 `Astro.locals.runtime.env`。`getEnv()` 只能在 `prerender = false` 的頁面／endpoint 用。
- **資料層**：`getDb(getEnv().DB)` → Drizzle；查詢集中在 `src/data/content.ts`，schema 在 `src/db/schema.ts`。改 schema 後跑 `npm run db:generate` 產生 migration。
- **Seed 與 migration 是分開的**：`db:migrate:local` / `db:migrate` 只套 migrations，`scripts/seed.sql` 要用 `db:seed:local` / `db:seed` 另外執行；seed 可重複跑。**`seed.sql` 必須放喺 `migrations/` 以外**，因為 `wrangler d1 migrations apply` 會將 `migrations_dir`（`wrangler.jsonc`，預設 `migrations`）內所有 `.sql` 當成 migration。
- **表單驗證集中在 `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` 產生再貼上，未貼前無法部署。R2 bucket 唔使貼 id，用 `r2:create`（或 `npm run setup`）建立即可，binding 係 `MEDIA`。
- **圖片上傳**：圖片存 Cloudflare R2（binding `MEDIA`、bucket `yingfung-solar-media`），由同一個 Worker 的 `/media/*` 出圖；上傳經 `/admin/upload`，client 端先縮圖轉 WebP。本機靠 `platformProxy` 模擬 R2，雲端要先 `npm run r2:create`。圖片欄位仍可貼 URL；換圖／刪除時 `lib/media.ts` 會清舊 R2 檔。
- **上線前要改 `astro.config.mjs` 的 `site`**：sitemap / canonical / OG 全部靠它（現為 `https://example.com`）。
- **追蹤分析（GA4 / Meta Pixel）**：ID 存 `site_settings`（`ga4_measurement_id` / `meta_pixel_id`，**空字串＝關閉**），喺 `/admin/settings` 改。`Base.astro` 只會喺用戶同意（`localStorage.cookie_consent`）之後先載入，未同意前唔會有追蹤請求／Cookie；`/privacy` 有說明同「重設 Cookie 偏好」。因為係通用 key-value，**冇新 migration**，只需 `scripts/seed.sql` 有 default。
- **後台認證**：`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。
- **語言**：UI 文案、註解、後台全部都係繁體中文（廣東話）——新增內容請保持一致；網站只做中文，不做雙語。
- `dist/`、`.astro/`、`.wrangler/`、`worker-configuration.d.ts` 都係產生檔，唔好手改。
- `docs/superpowers/` 有設計規格與實作計劃，係設計決策的權威來源。

# DOX framework

- DOX is highly performant AGENTS.md hierarchy installed here
- Agent must follow DOX instructions across any edits

## Core Contract

- AGENTS.md files are binding work contracts for their subtrees
- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it

## Read Before Editing

1. Read the root AGENTS.md
2. Identify every file or folder you expect to touch
3. Walk from the repository root to each target path
4. Read every AGENTS.md found along each route
5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX

Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.

## Update After Editing

Every meaningful change requires a DOX pass before the task is done.

Update the closest owning AGENTS.md when a change affects:

- purpose, scope, ownership, or responsibilities
- durable structure, contracts, workflows, or operating rules
- required inputs, outputs, permissions, constraints, side effects, or artifacts
- user preferences about behavior, communication, process, organization, or quality
- AGENTS.md creation, deletion, move, rename, or index contents

Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.

## Hierarchy

- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
- Each parent explains what its direct children cover and what stays owned by the parent
- The closer a doc is to the work, the more specific and practical it must be

## Child Doc Shape

- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists

Default section order:

- Purpose
- Ownership
- Local Contracts
- Work Guidance
- Verification
- Child DOX Index

## Style

- Keep docs concise, current, and operational
- Document stable contracts, not diary entries
- Put broad rules in parent docs and concrete details in child docs
- Prefer direct bullets with explicit names
- Do not duplicate rules across many files unless each scope needs a local version
- Delete stale notes instead of explaining history
- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist

## Closeout

1. Re-check changed paths against the DOX chain
2. Update nearest owning docs and any affected parents or children
3. Refresh every affected Child DOX Index
4. Remove stale or contradictory text
5. Run existing verification when relevant
6. Report any docs intentionally left unchanged and why

## User Preferences

When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md

## Child DOX Index

| Path | Scope |
|---|---|
| `src/AGENTS.md` | 原始碼全層：架構、跨層慣例；擁有 `theme/`、`layouts/`、`schemas/`、`config.ts`、`middleware.ts`、`env.d.ts`、`components/admin/`，以及 `pages/` 路由與 `/admin` 後台合約 |
| `src/components/site/AGENTS.md` | 前台 React island 與 Chakra UI 元件 |
| `src/data/AGENTS.md` | D1 讀取查詢層與後台設定欄位定義 |
| `src/db/AGENTS.md` | Drizzle schema（migration 的唯一來源） |
| `src/lib/AGENTS.md` | auth / env / db / form / media / ai / markdown 基礎工具 |
| `migrations/AGENTS.md` | D1 migration SQL（`migrations_dir` 內所有 `.sql` 都當 migration；seed 喺 `scripts/`） |
| `docs/AGENTS.md` | 設計規格與實作計劃（`superpowers/` 為設計權威） |

Project-level files with no child doc are owned by this root: `astro.config.mjs`、`wrangler.jsonc`、`drizzle.config.ts`、`tsconfig.json`、`package.json`、`README.md`、`.dev.vars.example`、`scripts/`（含 `setup.mjs` 同 `seed.sql`）。