104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# 盈豐太陽能工程有限公司 — 官網（村屋太陽能）
|
||
|
||
**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`）
|
||
- 真實工程相片（現時用佔位圖）
|