# 盈豐太陽能工程有限公司 — 官網設計規格 (Design Spec) - **日期**：2026-09-11 - **專案代號**：yingfungsolar - **狀態**：已與客戶確認方向，待寫實作計劃 --- ## 1. 背景與目標為香港**村屋太陽能**興建公司「盈豐太陽能工程有限公司」建立一個可以**完全部署在 Cloudflare** 的網站，包含： - 面向公眾的一頁式官網 - 一個 Blog 分頁（列表 + 文章頁） - 一個後台 `/admin`，讓非技術人員管理 Blog 及首頁內容設計要求：美觀、現代化、清爽。內容參考 BrightSun Solar（村屋及工廈太陽能），但**本網站只做村屋**，而且版面設計不參考該站。 ### 非目標 (Out of scope) - 不做工廈 / 農地太陽能內容 - 不做雙語（只做繁體中文） - 不做聯絡表單（只做 WhatsApp / 電話 / Email 連結） - 不做圖片上傳（先用佔位圖，後台以 URL 貼圖） - 不做多頁公司介紹（關於我們等內容併入一頁式） --- ## 2. 技術架構沿用現有 `cf-dash` 骨幹，路線 A：**Astro + React islands + Chakra UI**。 ``` ┌──────────────── Cloudflare Worker (一個 deploy) ────────────────┐ 瀏覽器 → │ Astro 7 │ │ ├─ / SSR，讀 D1 → React island (Chakra UI) │ │ ├─ /blog SSR，讀 D1 │ │ ├─ /blog/[slug] SSR，讀 D1 + Markdown 渲染 │ │ ├─ /admin/* SSR，Astro 表單 + HMAC cookie auth │ │ ├─ /sitemap.xml SSR，讀 D1 │ │ └─ /robots.txt 靜態 │ │ │ │ │ D1 (SQLite) ← Drizzle ORM │ │ KV (CACHE) ← 內容版本快取 (可選) │ └────────────────────────────────────────────────────────────────────┘ ``` ### 技術選型 | 層 | 選用 | 說明 | |---|---|---| | 框架 | Astro 7 (`output: "static"` + per-page `prerender = false`) | 沿用現有 | | Adapter | `@astrojs/cloudflare` | 沿用現有 | | UI | `@chakra-ui/react` v3 + `@emotion/react`（只淺色模式，不引入 color mode 套件） | 新增 | | React | React 19（由 `npx astro add react` 加入） | 新增 | | DB | Cloudflare D1 (SQLite) | 沿用 | | ORM | Drizzle | 沿用 | | Auth | HMAC-signed cookie（`src/lib/auth.ts`） | 沿用 | | Markdown | `marked`（`src/lib/markdown.ts`） | 沿用 | ### 關鍵渲染決策 1. **首頁改為 SSR**（`prerender = false`），因為首頁內容由 D1 提供、後台改完要即時生效。 - 用 `Cache-Control: public, s-maxage=60, stale-while-revalidate=300` 保持效能。 2. **每個頁面用單一 React root island**（`client:load`），入面包一個 ``。 - 原因：Chakra 的 Provider 只需一個；避免多個 island 各自建立 Provider 造成樣式重複。 - Astro 會 SSR render 呢個 island（SEO 無損），再喺 client hydrate。 3. **Chakra v3 SSR 樣式注入**：**已用 spike 實測驗證可行**。 - Versions: Astro 7.3.2 + `@astrojs/react` 6.0.5 + React 19.3 + `@chakra-ui/react` 3.37 + `@emotion/react` 11.14。 - 實測結果：SSR 會將 critical CSS 以 inline `