docs: admin dashboard redesign spec and plan

2026-09-13 21:41:06 +08:00
parent fbc562f495
commit e7ddbb6654
2 changed files with 265 additions and 0 deletions
@@ -0,0 +1,76 @@
+# 盈豐太陽能 — 後台 Dashboard 化重新設計 (Redesign Spec)
+
+- **日期**：2026-09-13
+- **狀態**：已與客戶確認方向
+- **背景**：現時 `/admin` 後台用綠色（`#0b8a5e`）／淺綠底（`#f2f8f6`）純 CSS，同前台 editorial（暖米白＋琥珀金＋墨黑）唔一致；一入 `/admin` 就係文章表，冇總覽。本規格將後台改造成墨黑 sidebar + 米白內容嘅真 dashboard。
+- **範圍**：只改後台（`src/layouts/AdminLayout.astro`、`src/pages/admin/**`、`src/data/content.ts`、`src/AGENTS.md`）。**唔郁**前台、D1 schema、migration、認證／middleware 邏輯。
+
+---
+
+## 1. 設計方向
+
+**墨黑 sidebar × 暖米白內容 × 琥珀金 accent** 嘅工具感 dashboard，同前台品牌一致但偏實用。
+
+- 沿用前台語意色：墨黑 `#1A1917`、暖米白 `#FAF8F4`、髮絲線 `#E7E2D9`、暖灰 `#6E6862`、琥珀 `#D97706`／`#B45309`。
+- 狀態色只用嚟表達語意，唔做裝飾：成功 `#0F6E56`、警示／草稿琥珀、危險 `#A32D2D`。
+- 形狀：直角／微圓角（4–8px）、髮絲邊框、無陰影、無漸層。
+- 純 Astro SSR + CSS（CSS variables），**唔引入 React / Chakra**，維持現有 admin 合約。
+
+## 2. 資訊架構
+
+- **`/admin`（總覽）**：dashboard，見 §3。
+- **`/admin/posts`（文章）**：由原 `index.astro` 文章列表搬過來。
+- 其餘路由不變：`/admin/content/[kind]`、`/admin/cases`、`/admin/ai`、`/admin/settings`、`/admin/post/[id]`、`/admin/login`、`/admin/logout`。
+
+### Shell（`AdminLayout.astro`）
+
+- 桌面（≥900px）：左側固定 sidebar 248px、墨黑底；內容區暖米白、`max-width 1080px`。
+- Sidebar：品牌 serif「盈豐太陽能」＋細字「後台」；導航分組：
+  - **總覽** → `/admin`
+  - **內容管理** → 文章 `/admin/posts`、服務、特色、流程、常見問題、完成案例
+  - **系統** → AI 生成、網站設定
+  - 底部：睇網站 ↗（新視窗）、登出
+- Active 項：琥珀文字＋左邊 3px 琥珀條＋微亮底。
+- 手機（<900px）：sidebar 收埋，頂欄顯示品牌＋純 CSS checkbox 漢堡開合。
+- 所有色值集中做 CSS variables（`--ink`／`--ink-2`／`--bg`／`--surface`／`--fg`／`--fg-muted`／`--border`／`--brand`／`--brand-strong`／`--brand-soft`／`--ok`／`--warn`／`--danger`／`--radius-sm`／`--radius`／`--sidebar-w`）。
+- 保留原有 R2 上傳 `<script>` 同 `ImageField` 依賴嘅 `.image-url` / `.image-preview` / `.image-status` class。
+
+## 3. `/admin` 總覽內容
+
+- 頁首：h1「總覽」＋更新時間。
+- **統計卡 ×4**（大 serif 琥珀數字、髮絲邊框、無陰影）：
+  1. 文章 — 總數；細字：已發布 N · 草稿 N
+  2. 完成案例 — 總數；細字：已發布 N · 草稿 N
+  3. 首頁內容 — 總數；細字：服務 · 特色 · 流程 · FAQ
+  4. 關鍵字佇列 — 待生成數；細字：已生成 N · 已略過 N
+- **待辦提示**（主欄）：條件式列出，每項可點去對應頁；全清顯示「一切妥當」：
+  - N 篇文章仍是草稿 → `/admin/posts`
+  - N 篇文章未有封面圖 → `/admin/posts`
+  - N 個關鍵字待生成 → `/admin/ai`
+  - N 個案例仍是草稿 → `/admin/cases`
+  - N 個首頁內容項目仍是草稿 → `/admin/content/service`
+- **系統狀態**（側欄）：AI 生成 啟用／停用、`AI_API_KEY`／`TAVILY_API_KEY` 已設定／未設定、目前 model 與 Base URL（唯讀顯示）。
+- **最近更新文章**（全寬）：最新 5 篇（標題＋slug、狀態 badge、更新日期、編輯 link），section 右上「+ 寫新文」。
+
+## 4. 資料層
+
+- `src/data/content.ts` 加 `getDashboardData(db): Promise<DashboardData>`，集中提供 dashboard 統計（沿用「查詢集中喺 content.ts」慣例）。
+- `DashboardData`：`posts{published,draft}`、`cases{published,draft}`、`content[{kind,published,draft}]`、`keywords{pending,generated,skipped}`、`recentPosts`、`postsWithoutCover`。
+- `getDashboardData` 只讀 DB；AI secrets（`env.AI_API_KEY`／`env.TAVILY_API_KEY`）同 `ai_enabled` 喺頁面層處理。
+- **冇 schema 改動、冇 migration。**
+
+## 5. 各頁統一
+
+- `cases`／`content/[kind]`／`settings`／`ai` 只改外觀（卡片、badge、掣、表格、提示），表單 action 同流程不變。
+- badge：已發布＝淡綠、草稿＝琥珀、已略過／muted＝灰；成功提示由 `.badge.published` 改為 `.notice`。
+- `post/[id].astro` 存／刪／取消後 redirect 去 `/admin/posts`。
+- `login.astro` 用同一 tokens 重新上色。
+
+## 6. 驗證
+
+- `npm run build`（唯一自動驗證；專案冇 test／lint／typecheck）。
+- `npm run dev` 目測：所有 admin 頁、RWD（≥900 / <900）、登入／登出、圖片上傳、表單存檔 redirect、`/blog/[slug]` 404 不受影響。
+
+## 7. 文件同步
+
+- `src/AGENTS.md` Admin 段落：`/admin` 由文章列表改為總覽、文章列表喺 `/admin/posts`、`AdminLayout` 改為墨黑 sidebar shell、色系改用 CSS variables、`getDashboardData` 位置。