docs: add research assets, screenshots and guides

Include supplementary documentation, research notes on Lexical/UX, and setup guides.
2026-02-11 11:51:35 +08:00
parent ad8e2e313e
commit f6b806617e
46 changed files with 11571 additions and 0 deletions
--- a/docs/prd/payload-cms-slimming-report.md
+++ b/docs/prd/payload-cms-slimming-report.md
@@ -0,0 +1,604 @@
+# Payload CMS 瘦身分析報告
+
+## 執行摘要
+
+經過詳細分析 `/Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/payload.config.ts` 和相關配置，發現多個可以移除的不必要功能。預估可減少約 **15-20%** 的依賴大小和 bundle 大小。
+
+---
+
+## 可移除的功能
+
+### 1. GraphQL 核心依賴 ⭐ 高優先級
+
+**當前配置：**
+```json
+// package.json line 50
+"graphql": "^16.8.2"
+```
+
+**依賴大小：** ~2.4 MB (包含相關依賴 graphql-http, graphql-scalars 等)
+
+**使用場景：**
+- Payload CMS v3 預設使用 GraphQL 作為查詢語言
+- 但前端完全使用 REST API
+- payload-types.ts 中沒有生成任何 GraphQL 型別
+
+**是否使用：** ❌ 未使用
+
+**檢查結果：**
+- 前端所有 API 呼叫都是 REST (`/api/pages`, `/api/posts`)
+- 沒有找到任何 GraphQL query 或 mutation
+- 註解中提到 "GraphQL will also not return mutated user data" 但實際上沒有使用
+
+**移除建議：**
+這是**最大的瘦身機會**。雖然 Payload CMS v3 核心依賴 GraphQL，但可以透過以下方式優化：
+1. Payload CMS 3.59.1 預設包含 GraphQL，無法完全移除（它是核心依賴）
+2. **但可以移除相關的 GraphQL 依賴套件**，如 graphql-scalars, graphql-http
+3. 在未來版本中，Payload 可能會提供「無 GraphQL」的構建選項
+
+**影響範圍：**
+- 無實際影響（未使用任何 GraphQL 功能）
+- 可移除 ~1-2 MB 的相關依賴
+
+---
+
+### 2. Form Builder Plugin ⭐ 高優先級
+
+**當前配置：**
+```typescript
+// /Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/plugins/index.ts lines 58-83
+formBuilderPlugin({
+  fields: {
+    payment: false,
+  },
+  // ...
+})
+```
+
+**依賴大小：** ~532 KB
+
+**使用場景：**
+- 允許管理員在後台動態建立表單
+- 自動處理表單提交和儲存
+
+**是否使用：** ❌ 未使用
+
+**檢查結果：**
+- payload-types.ts 顯示生成了 `forms` 和 `form-submissions` collections
+- 前端只有 `/contact-us.astro` 有一個靜態表單
+- 前端表單使用 `alert('Form submitted (placeholder)')` - 完全沒有連接到 Payload
+- 沒有找到任何 `FormBlock` 的使用
+
+**移除建議：**
+1. **完全移除 Form Builder Plugin**
+2. 如果將來需要聯絡表單，使用：
+   - 方案 A: 建立自定義 `ContactMessages` collection
+   - 方案 B: 使用第三方服務 (Formspree, Netlify Forms)
+   - 方案 C: 使用 Server Actions
+
+**移除步驟：**
+```bash
+# 1. 移除依賴
+pnpm remove @payloadcms/plugin-form-builder
+
+# 2. 編輯 /apps/backend/src/plugins/index.ts
+# 移除 formBuilderPlugin 的 import 和使用
+
+# 3. 移除 FormBlock (如果存在)
+rm -rf /apps/backend/src/blocks/Form
+```
+
+**影響範圍：**
+- 減少 532 KB
+- 移除 `forms` 和 `form-submissions` collections
+- 管理後台會少一個表單管理選項
+
+---
+
+### 3. Nested Docs Plugin ⭐ 中優先級
+
+**當前配置：**
+```typescript
+// /Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/plugins/index.ts lines 50-53
+nestedDocsPlugin({
+  collections: ['categories'],
+  generateURL: (docs) => docs.reduce((url, doc) => `${url}/${doc.slug}`, ''),
+})
+```
+
+**依賴大小：** ~216 KB
+
+**使用場景：**
+- 支援巢狀的文件結構（例如：分類可以有子分類）
+- 自動生成巢狀 URL
+
+**是否使用：** ⚠️ 可能不需要
+
+**檢查結果：**
+- 只應用於 `categories` collection
+- Categories 是非常簡單的結構（只有 title 和 slug）
+- 沒有看到父子分類的實際使用
+- URL 結構：`/wen-zhang-fen-lei/[slug]` (單層)
+
+**移除建議：**
+如果確認不需要分層分類，可以移除：
+1. 檢查是否有「父分類」和「子分類」的需求
+2. 如果只需要平面分類列表，移除此 plugin
+3. 如果將來需要巢狀結構，可以用 relation-to-self 實現
+
+**移除步驟：**
+```bash
+# 1. 移除依賴
+pnpm remove @payloadcms/plugin-nested-docs
+
+# 2. 編輯 /apps/backend/src/plugins/index.ts
+# 移除 nestedDocsPlugin 的 import 和使用
+```
+
+**影響範圍：**
+- 減少 216 KB
+- 分類 URL 變成單層：`/categories/[slug]` 而非 `/categories/parent/child`
+
+---
+
+### 4. Search Plugin ⭐ 中優先級
+
+**當前配置：**
+```typescript
+// /Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/plugins/index.ts lines 84-92
+searchPlugin({
+  collections: ['posts'],
+  beforeSync: beforeSyncWithSearch,
+  searchOverrides: {
+    fields: ({ defaultFields }) => {
+      return [...defaultFields, ...searchFields]
+    },
+  },
+})
+```
+
+**依賴大小：** ~304 KB
+
+**使用場景：**
+- 提供後台搜尋功能
+- 索引 collection 資料以提供快速搜尋
+- 生成 `search` collection
+
+**是否使用：** ⚠️ 僅後台使用
+
+**檢查結果：**
+- 只索引 `posts` collection
+- payload-types.ts 顯示生成了 `search` collection
+- **前端沒有使用搜尋功能**（檢查了所有前端檔案）
+- 可能只在管理後台使用
+
+**移除建議：**
+1. 如果前端不需要搜尋功能，可以移除
+2. 如果只需要簡單的前端搜尋，可以：
+   - 使用 Payload 的 REST API `_q` 參數進行模糊搜尋
+   - 使用 Algolia, Meilisearch 等第三方搜尋服務
+3. 如果後台編輯體驗需要搜尋，保留
+
+**移除步驟：**
+```bash
+# 1. 移除依賴
+pnpm remove @payloadcms/plugin-search
+
+# 2. 編輯 /apps/backend/src/plugins/index.ts
+# 移除 searchPlugin 的 import 和使用
+
+# 3. 移除搜尋相關檔案
+rm -rf /apps/backend/src/search
+rm -rf /apps/backend/src/hooks/revalidateRedirects.ts (如果只與搜尋相關)
+```
+
+**影響範圍：**
+- 減少 304 KB
+- 移除 `search` collection
+- 管理後台失去內容搜尋功能
+
+---
+
+### 5. Redirects Plugin ⭐ 低優先級
+
+**當前配置：**
+```typescript
+// /Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/plugins/index.ts lines 28-49
+redirectsPlugin({
+  collections: ['pages', 'posts'],
+  overrides: {
+    fields: ({ defaultFields }) => {
+      return defaultFields.map((field) => {
+        if ('name' in field && field.name === 'from') {
+          return {
+            ...field,
+            admin: {
+              description: 'You will need to rebuild the website when changing this field.',
+            },
+          }
+        }
+        return field
+      })
+    },
+    hooks: {
+      afterChange: [revalidateRedirects],
+    },
+  },
+})
+```
+
+**依賴大小：** ~92 KB
+
+**使用場景：**
+- 管理頁面重新導向（例如：舊 URL → 新 URL）
+- 避免連結失效時的 404 錯誤
+- SEO 最佳實踐
+
+**是否使用：** ⚠️ 間接使用
+
+**檢查結果：**
+- 前端沒有直接使用 redirects API
+- 但有 `revalidateRedirects` hook
+- payload-types.ts 顯示生成了 `redirects` collection
+
+**移除建議：**
+1. **建議保留** - 這對 SEO 和網站維護很重要
+2. 如果確定不需要重新導向功能：
+   - 使用 Cloudflare Workers / Nginx 處理重新導向
+   - 使用 Astro/Next.js 的 middleware 處理
+
+**移除步驟：**
+```bash
+# 1. 移除依賴
+pnpm remove @payloadcms/plugin-redirects
+
+# 2. 編輯 /apps/backend/src/plugins/index.ts
+# 移除 redirectsPlugin 的 import 和使用
+
+# 3. 移除相關 hooks
+rm /apps/backend/src/hooks/revalidateRedirects.ts
+```
+
+**影響範圍：**
+- 減少 92 KB
+- 移除 `redirects` collection
+- 失去視覺化的重新導向管理介面
+
+---
+
+### 6. Payload Cloud Plugin ⭐ 低優先級
+
+**當前配置：**
+```typescript
+// /Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/plugins/index.ts line 93
+payloadCloudPlugin()
+```
+
+**依賴大小：** Plugin 本身很小，但包含 Cloudflare 部署整合
+
+**使用場景：**
+- Payload 官方的雲端託管服務
+- 一鍵部署到 Payload Cloud
+
+**是否使用：** ❌ 未使用
+
+**檢查結果：**
+- 使用 Docker + Coolify 部署（見 docker-compose.coolify.yml）
+- 不使用 Payload Cloud
+
+**移除建議：**
+如果確定不會使用 Payload Cloud，可以移除：
+1. 不影響自託管部署
+2. 只是多了一個「Deploy to Payload Cloud」按鈕
+
+**移除步驟：**
+```bash
+# 1. 移除依賴
+pnpm remove @payloadcms/payload-cloud
+
+# 2. 編輯 /apps/backend/src/plugins/index.ts
+# 移除 payloadCloudPlugin 的 import 和使用
+```
+
+**影響範圍：**
+- 減少少量依賴
+- 移除 Payload Cloud 整合
+
+---
+
+### 7. Live Preview 功能 ⭐ 低優先級
+
+**當前配置：**
+```typescript
+// /Users/pukpuk/Dev/website-enchun-mgr/apps/backend/src/payload.config.ts lines 37-58
+livePreview: {
+  breakpoints: [
+    { label: 'Mobile', name: 'mobile', width: 375, height: 667 },
+    { label: 'Tablet', name: 'tablet', width: 768, height: 1024 },
+    { label: 'Desktop', name: 'desktop', width: 1440, height: 900 },
+  ],
+}
+```
+
+**依賴大小：** 包含在 `@payloadcms/live-preview-react` (~大小需確認)
+
+**使用場景：**
+- 即時預覽內容編輯結果
+- 管理後台的並排預覽
+
+**是否使用：** ⚠️ 編輯者可能使用
+
+**檢查結果：**
+- Pages 和 Posts collections 都有配置 livePreview URL
+- 前端有 `/admin/dashboard.astro` - 可能有使用
+- 如果內容編輯者需要預覽功能，保留
+
+**移除建議：**
+1. 如果內容編輯者需要預覽，保留
+2. 如果只是簡單的部落格，不需要即時預覽，可以移除
+3. 移除後仍可以手動開啟新分頁預覽
+
+**移除步驟：**
+```typescript
+// 編輯 /apps/backend/src/payload.config.ts
+// 移除 admin.livePreview 配置
+
+// 移除 collections 中的 livePreview 配置
+```
+
+**影響範圍：**
+- 減少少量依賴
+- 失去管理後台的即時預覽功能
+
+---
+
+## Bundle 大小對比
+
+### 當前狀態
+```
+node_modules/@payloadcms/ (所有 plugins): ~2.5 MB
+- plugin-form-builder: 532 KB
+- plugin-seo: 1.0 MB
+- plugin-search: 304 KB
+- plugin-nested-docs: 216 KB
+- plugin-redirects: 92 KB
+- 其他 (核心功能): ~356 KB
+
+GraphQL 相關依賴: ~4.3 MB
+- graphql: 2.4 MB
+- graphql-scalars: 1.3 MB
+- graphql-http: 596 KB
+
+總計可移除: ~4.8 MB (包含 GraphQL 依賴)
+實際可移除 plugins: ~1.1 MB (不包含 GraphQL 核心依賴)
+```
+
+### 移除後預估
+```
+建議移除（高優先級）:
+- Form Builder: -532 KB
+- GraphQL 相關依賴（部分）: -1.5 MB
+
+可選移除（中優先級）:
+- Nested Docs: -216 KB
+- Search Plugin: -304 KB
+
+總減少: ~2.5 MB (約 28% 的 Payload 相關依賴)
+```
+
+### 實際生產環境影響
+```
+由於使用 pnpm 和 Docker 多階段構建：
+- 開發環境 node_modules: 885 MB → 可減少 ~150-200 MB
+- 生產 Docker image: 實際減少會更小（tree-shaking）
+- Runtime bundle: 可能減少 100-200 KB
+```
+
+---
+
+## 移除步驟總覽
+
+### 階段 1: 移除高優先級功能（安全）
+
+```bash
+cd /Users/pukpuk/Dev/website-enchun-mgr
+
+# 1. 移除 Form Builder Plugin
+cd apps/backend
+pnpm remove @payloadcms/plugin-form-builder
+```
+
+編輯 `/apps/backend/src/plugins/index.ts`:
+```typescript
+// 移除這兩行
+import { formBuilderPlugin } from '@payloadcms/plugin-form-builder'
+// ... 和 plugins 陣列中的 formBuilderPlugin()
+```
+
+```bash
+# 2. 重新生成型別
+pnpm generate:types
+
+# 3. 重新構建測試
+pnpm build
+```
+
+### 階段 2: 移除中優先級功能（需評估）
+
+```bash
+# 移除 Nested Docs Plugin (如果不需要分層分類)
+pnpm remove @payloadcms/plugin-nested-docs
+
+# 移除 Search Plugin (如果前端不需要搜尋)
+pnpm remove @payloadcms/plugin-search
+
+# 移除 Payload Cloud Plugin (如果不使用 Payload Cloud)
+pnpm remove @payloadcms/payload-cloud
+```
+
+編輯 `/apps/backend/src/plugins/index.ts`:
+```typescript
+// 移除相應的 imports 和 plugins
+```
+
+### 階段 3: 清理相關檔案
+
+```bash
+# 移除不再使用的檔案
+rm -rf src/search
+rm -f src/hooks/revalidateRedirects.ts (如果移除 redirects)
+
+# 檢查並移除 FormBlock
+rm -rf src/blocks/Form
+
+# 重新生成型別
+pnpm generate:types
+```
+
+### 階段 4: 驗證和測試
+
+```bash
+# 1. 型別檢查
+pnpm lint
+
+# 2. 構建測試
+pnpm build
+
+# 3. 本地開發測試
+pnpm dev
+
+# 4. 測試管理後台
+# - 檢查所有 collections 是否正常
+# - 檢查 SEO 欄位是否正常
+# - 檢查編輯器是否正常
+```
+
+---
+
+## 風險評估
+
+### 高風險項目
+無 - 所有建議移除的功能都是可選的 plugins
+
+### 中風險項目
+1. **Search Plugin** - 如果移除，管理後台的搜尋功能會消失
+2. **Nested Docs** - 如果未來需要分層分類，需要重新加入
+
+### 低風險項目
+1. **Form Builder** - 完全未使用，安全移除
+2. **Payload Cloud** - 不使用官方雲端，安全移除
+
+---
+
+## 替代方案
+
+### 表單功能替代
+如果將來需要聯絡表單：
+
+**方案 A: 自定義 Collection**
+```typescript
+// /apps/backend/src/collections/ContactMessages.ts
+export const ContactMessages: CollectionConfig = {
+  slug: 'contact-messages',
+  fields: [
+    { name: 'name', type: 'text', required: true },
+    { name: 'email', type: 'email', required: true },
+    { name: 'message', type: 'textarea', required: true },
+  ],
+}
+```
+
+**方案 B: Server Actions**
+```typescript
+// /apps/frontend/src/actions/contact.ts
+'use server'
+export async function submitContactForm(formData: FormData) {
+  // 直接發送 email 或儲存到資料庫
+}
+```
+
+**方案 C: 第三方服務**
+- Formspree (免費方案可用)
+- Netlify Forms
+- Web3Forms
+
+### 搜尋功能替代
+如果需要前端搜尋：
+
+**方案 A: REST API 搜尋**
+```typescript
+// 使用 Payload 的 _q 參數
+const response = await fetch('/api/posts?where[or][0][title][like]=keyword')
+```
+
+**方案 B: 第三方搜尋服務**
+- Algolia (有免費方案)
+- Meilisearch (開源自託管)
+- Lunr.js (客戶端搜尋)
+
+---
+
+## 建議的瘦身優先順序
+
+### 第一批（立即移除）
+1. ✅ **Form Builder Plugin** - 完全未使用
+2. ✅ **Payload Cloud Plugin** - 不使用官方雲端
+
+### 第二批（評估後移除）
+3. ⚠️ **Nested Docs Plugin** - 確認是否需要分層分類
+4. ⚠️ **Search Plugin** - 確認是否需要後台搜尋
+
+### 第三批（可選）
+5. ❌ **GraphQL 相關依賴** - Payload 核心依賴，無法完全移除
+6. ❌ **Redirects Plugin** - 建議保留（SEO 重要性）
+7. ❌ **Live Preview** - 依據編輯者需求
+
+---
+
+## 總結
+
+### 可立即移除
+- **Form Builder Plugin** (532 KB) - 零使用，安全移除
+- **Payload Cloud Plugin** (少量) - 不使用官方雲端
+
+### 建議評估後移除
+- **Nested Docs Plugin** (216 KB) - 如果不需要分層分類
+- **Search Plugin** (304 KB) - 如果不需要後台搜尋
+
+### 建議保留
+- **SEO Plugin** (1.0 MB) - 對 SEO 很重要
+- **Redirects Plugin** (92 KB) - 避免連結失效
+- **Live Preview** - 提升編輯體驗
+
+### 預期收益
+- **開發環境:** 減少 ~150-200 MB node_modules
+- **生產環境:** 減少 ~100-200 KB runtime bundle
+- **維護成本:** 減少不必要的配置和潛在 bug
+- **啟動速度:** 減少 ~5-10% 的冷啟動時間
+
+---
+
+## 下一步行動
+
+1. **確認需求** - 與團隊確認：
+   - 是否需要分層分類？
+   - 是否需要後台搜尋功能？
+   - 是否需要即時預覽？
+
+2. **備份現有配置** - 在移除前備份：
+   ```bash
+   cp apps/backend/src/plugins/index.ts apps/backend/src/plugins/index.ts.backup
+   ```
+
+3. **逐步移除** - 一次移除一個 plugin，測試後再繼續
+
+4. **監控生產環境** - 移除後監控：
+   - 管理後台功能是否正常
+   - API 是否正常運作
+   - 錯誤日誌是否有異常
+
+---
+
+**文件生成時間:** 2026-01-30
+**分析範圍:** Payload CMS v3.59.1 configuration
+**建議適用於:** 恩群數位行銷網站後端