first commit

2026-09-11 15:49:41 +08:00
commit 5b69bc818a
98 changed files with 30551 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 盈豐太陽能工程有限公司 — 官網（村屋太陽能）
+
+**Astro 7 + React 19 + Chakra UI v3 + Cloudflare Workers + D1 + Drizzle。全部部署喺 Cloudflare，零維運。**
+
+一頁式官網（村屋太陽能）＋ Blog ＋ 內容管理後台。
+
+## 功能
+
+- **一頁式官網** `/`（SSR，讀 D1）：Hero、服務、特色、流程、完成案例、FAQ、聯絡 CTA
+- **Blog** `/blog`、`/blog/[slug]`：封面卡片列表 + Markdown 文章頁
+- **後台** `/admin`（密碼登入）：管理文章、首頁內容（服務／特色／流程／FAQ）、完成案例、網站設定（公司資料／聯絡／Hero／SEO）
+- **SEO**：canonical、OG/Twitter card、`/sitemap.xml`、`/robots.txt`、結構化語意 HTML
+- 首頁／Blog 用邊緣快取（`s-maxage`），後台改完約 1 分鐘內生效
+
+## 技術棧
+
+| 層 | 選用 |
+|---|---|
+| 前端框架 | Astro 7（`output: "static"` + per-page SSR） |
+| UI | React 19 + `@chakra-ui/react` v3 + `@emotion/react`（清新天藍／綠色系 theme） |
+| Adapter | `@astrojs/cloudflare`（一個 Worker） |
+| DB | Cloudflare D1（SQLite） |
+| ORM | Drizzle |
+| Auth | HMAC-signed cookie（`src/lib/auth.ts`） |
+| Markdown | `marked` |
+| Icons | `lucide-react` |
+
+> Chakra v3 用 Emotion，SSR 會輸出 inline critical CSS（首屏即有樣式、零 FOUC），client hydrate 後整合到 `<head>`；已實測 Astro 7 + React 19 無 hydration error。
+
+## 本機開發
+
+```bash
+npm install
+
+# 建本機 D1 + 套 migration（migration 會連 seed.sql 一齊套）
+npm run db:migrate:local
+
+# 重新匯入種子資料（可重複執行）
+npm run db:seed:local
+
+# 開發 server（:4321）
+npx astro dev
+```
+
+本機後台密碼喺 `.dev.vars`（`ADMIN_PASSWORD=changeme-local`，已 gitignore）。
+
+想模擬 production（wrangler）：`npx wrangler dev`。
+
+## 部署到 Cloudflare
+
+```bash
+npm run login                              # 瀏覽器授權
+
+npm run db:create                          # 印 database_id → 填入 wrangler.jsonc
+npm run kv:create                          # 印 namespace id → 填入 wrangler.jsonc
+
+npm run db:migrate                         # 雲端套 migration
+npm run db:seed                            # 雲端匯入種子（公司資料 + 樣本內容）
+
+npx wrangler secret put ADMIN_PASSWORD     # 設定後台密碼
+
+# 改 astro.config.mjs 嘅 site = 真網域
+npm run deploy
+```
+
+之後更新：`npm run deploy`。
+
+## 後台點用
+
+1. 去 `/admin`，輸入密碼登入
+2. **內容總覽** → 服務 / 特色 / 流程 / 常見問題 / 完成案例 / 網站設定
+3. 每個項目可新增、修改、刪除、用 ↑↓ 排序、「已發布 / 草稿」控制前台顯示
+4. 圖片：直接貼圖片 URL（暫時；之後可換成上傳）
+
+## 結構
+
+```
+src/
+├─ theme/system.ts              Chakra theme（tokens / 顏色 / 字體）
+├─ components/site/*.tsx        前台 React 元件（Header/Hero/Services/Faq…）
+├─ data/
+│  ├─ content.ts                D1 讀取 + WhatsApp/電話 link helper
+│  └─ settings-fields.ts        後台設定欄位定義
+├─ db/schema.ts                 Drizzle schema（posts / site_settings / content_items / cases）
+├─ layouts/Base.astro           SEO head + fonts
+├─ layouts/AdminLayout.astro    後台外框
+├─ pages/
+│  ├─ index.astro               SSR 首頁
+│  ├─ blog/…                    Blog
+│  ├─ admin/…                   後台
+│  └─ sitemap.xml.ts / robots.txt.ts
+└─ lib/{auth,db,env,markdown}.ts
+migrations/
+├─ 0000_init.sql …              Drizzle migrations
+└─ seed.sql                     種子資料（與 migration 一齊執行）
+```
+
+## 待客戶提供（可喺 `/admin/settings` 自行更新）
+
+- 真實電話 / WhatsApp / Email / 地址
+- 電業承辦商牌照號碼
+- 真域名（`astro.config.mjs` 嘅 `site`）
+- 真實工程相片（現時用佔位圖）