feat: Introduce FAQ and keywords fields to Posts collection for SEO, update payload types, and add related documentation.

2025-12-23 16:01:30 +08:00
parent ae9c3c236a
commit e80c82ea0a
3 changed files with 278 additions and 0 deletions
--- a/docs/CMS-Implementation-Plan-FAQ-Keywords.md
+++ b/docs/CMS-Implementation-Plan-FAQ-Keywords.md
@@ -0,0 +1,202 @@
+# PayloadCMS Implementation Plan: FAQ & Keywords Fields
+
+> **目的**：在 `~/Dev/website-ricenoodletw-cms/` 專案中新增 `faq` 和 `keywords` 欄位
+> 
+> **這份文件供另一個 Agent 在 CMS workspace 中執行**
+
+---
+
+## 概述
+
+在 PayloadCMS 的 `posts` collection 新增兩個欄位，讓每篇文章可以有獨立的 FAQ 和關鍵字，前端會自動產生對應的 JSON-LD 結構化資料。
+
+---
+
+## 步驟 1：找到 Posts Collection 設定檔
+
+找到 `posts` collection 的設定檔，通常在：
+- `src/collections/Posts.ts`
+- `src/collections/posts.ts`
+- `collections/Posts.ts`
+
+---
+
+## 步驟 2：新增 FAQ 欄位
+
+在 `fields` 陣列中新增：
+
+```typescript
+{
+  name: 'faq',
+  type: 'array',
+  label: '文章專屬 FAQ',
+  admin: {
+    description: '為這篇文章新增 FAQ，將自動產生 FAQPage JSON-LD 結構化資料，有助於 SEO 和 Perplexity 引用',
+    condition: (data) => data?.status === 'published' || true, // 可選：條件顯示
+  },
+  fields: [
+    {
+      name: 'question',
+      type: 'text',
+      label: '問題',
+      required: true,
+      admin: {
+        placeholder: '例如：榕樹下米苔目為什麼有兩家？',
+      },
+    },
+    {
+      name: 'answer',
+      type: 'textarea',
+      label: '答案',
+      required: true,
+      admin: {
+        placeholder: '提供完整且有引用價值的答案...',
+      },
+    },
+  ],
+},
+```
+
+---
+
+## 步驟 3：新增 Keywords 欄位
+
+在 `fields` 陣列中新增：
+
+```typescript
+{
+  name: 'keywords',
+  type: 'array',
+  label: 'SEO 關鍵字',
+  admin: {
+    description: '文章關鍵字標籤，用於 JSON-LD 結構化資料',
+  },
+  fields: [
+    {
+      name: 'keyword',
+      type: 'text',
+      label: '關鍵字',
+      required: true,
+      admin: {
+        placeholder: '例如：台東美食',
+      },
+    },
+  ],
+},
+```
+
+---
+
+## 步驟 4：完整範例
+
+以下是完整的欄位定義，可直接複製貼上：
+
+```typescript
+// 加在 Posts collection 的 fields 陣列中
+// 建議放在 content 欄位之後，meta 欄位之前
+
+// FAQ 欄位
+{
+  name: 'faq',
+  type: 'array',
+  label: '文章專屬 FAQ',
+  admin: {
+    description: '每題 FAQ 會自動產生 FAQPage JSON-LD，有助於 Perplexity 等 AI 搜尋引擎引用',
+  },
+  fields: [
+    {
+      name: 'question',
+      type: 'text',
+      label: '問題',
+      required: true,
+    },
+    {
+      name: 'answer',
+      type: 'textarea',
+      label: '答案',
+      required: true,
+    },
+  ],
+},
+
+// Keywords 欄位
+{
+  name: 'keywords',
+  type: 'array',
+  label: 'SEO 關鍵字',
+  admin: {
+    description: '用於 Article schema 的 keywords 屬性',
+  },
+  fields: [
+    {
+      name: 'keyword',
+      type: 'text',
+      label: '關鍵字',
+      required: true,
+    },
+  ],
+},
+```
+
+---
+
+## 步驟 5：資料庫遷移
+
+修改 collection 後，根據你的設定：
+
+### 如果使用 MongoDB
+通常不需要額外遷移，新欄位會自動可用。
+
+### 如果使用 Postgres/SQLite
+可能需要執行：
+```bash
+npm run payload migrate:create
+npm run payload migrate
+```
+
+---
+
+## 步驟 6：驗證
+
+1. 重啟 CMS 開發伺服器
+2. 進入後台編輯任一文章
+3. 確認看到「文章專屬 FAQ」和「SEO 關鍵字」欄位
+4. 新增測試資料並儲存
+5. 透過 API 確認資料正確回傳：
+   ```
+   GET /api/posts?limit=1&depth=1
+   ```
+
+---
+
+## API 回傳格式
+
+新增欄位後，API 會回傳：
+
+```json
+{
+  "id": "...",
+  "title": "文章標題",
+  "faq": [
+    {
+      "question": "問題一",
+      "answer": "答案一"
+    },
+    {
+      "question": "問題二",
+      "answer": "答案二"
+    }
+  ],
+  "keywords": [
+    { "keyword": "台東美食" },
+    { "keyword": "米苔目" }
+  ]
+}
+```
+
+---
+
+## 相關文件
+
+- 前端 TypeScript 型別需同步更新：`src/types/blog.ts`
+- 前端 JSON-LD 產生邏輯：`src/pages/[category]/[slug].astro`