diff --git a/docs/CMS-Implementation-Plan-FAQ-Keywords.md b/docs/CMS-Implementation-Plan-FAQ-Keywords.md new file mode 100644 index 0000000..77c9500 --- /dev/null +++ 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` diff --git a/src/collections/Posts/index.ts b/src/collections/Posts/index.ts index 9a3d774..4256f12 100644 --- a/src/collections/Posts/index.ts +++ b/src/collections/Posts/index.ts @@ -140,6 +140,50 @@ export const Posts: CollectionConfig<'posts'> = { ], label: 'Meta', }, + { + label: 'SEO 強化', + fields: [ + { + 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, + }, + ], + }, + { + name: 'keywords', + type: 'array', + label: 'SEO 關鍵字', + admin: { + description: '用於 Article schema 的 keywords 屬性', + }, + fields: [ + { + name: 'keyword', + type: 'text', + label: '關鍵字', + required: true, + }, + ], + }, + ], + }, { name: 'meta', label: 'SEO', diff --git a/src/payload-types.ts b/src/payload-types.ts index b17811a..139fd15 100644 --- a/src/payload-types.ts +++ b/src/payload-types.ts @@ -233,6 +233,25 @@ export interface Post { }; relatedPosts?: (string | Post)[] | null; categories?: (string | Category)[] | null; + /** + * 每題 FAQ 會自動產生 FAQPage JSON-LD,有助於 Perplexity 等 AI 搜尋引擎引用 + */ + faq?: + | { + question: string; + answer: string; + id?: string | null; + }[] + | null; + /** + * 用於 Article schema 的 keywords 屬性 + */ + keywords?: + | { + keyword: string; + id?: string | null; + }[] + | null; meta?: { title?: string | null; /** @@ -1136,6 +1155,19 @@ export interface PostsSelect { content?: T; relatedPosts?: T; categories?: T; + faq?: + | T + | { + question?: T; + answer?: T; + id?: T; + }; + keywords?: + | T + | { + keyword?: T; + id?: T; + }; meta?: | T | {