BIGboss248/nextjs-wordpress

Next.js 頁面與路由開發 (nextjs-page-dev)

專門的工作流程，用於建立可供生產環境使用的 Next.js App Router 頁面，包含非同步路由參數、在地化翻譯字典、動態中繼資料、型別安全的 JSON-LD 結構化資料（schema-dts）以及靜態預先渲染。

[!TIP] 模組化資源與深度指南：

• 串流與 UI 邊界：references/streaming-and-boundaries.md
• 頁面慣例與生命週期：references/page-conventions-and-lifecycle.md
• SEO 與結構化資料指南：references/seo-structured-data-guide.md
• 可重複使用模板：resources/templates/
• 驗證腳本：scripts/verify-page.ps1（Windows）/ scripts/verify-page.sh（Linux）

---

架構規則與標準

1. 規劃情境與路由註冊表

• 讀取 docs/project.json 以解析 supported_languages、dictionaries_dir（預設值："messages"）以及 new_component_dir。
• 所有導航 URL 必須引用來自 @/lib/routes 或 @/i18n/navigation 的 ROUTES。
• 目標頁面路徑階層：app/[locale]/<route-path>/page.tsx（若是非在地化的頁面，則為 app/<route-path>/page.tsx）。

2. 零硬編碼與字典填充

• 無硬編碼文字： 在撰寫 JSX 之前，必須先將頁面標題、大標題、描述及靜態標籤新增到所有 supported_languages 的 messages/[locale].json 檔案中。
• RSC 翻譯： 在伺服器元件中使用 await getTranslations('<namespace>') 讀取翻譯。

3. SEO、中繼資料與 JSON-LD

• 動態中繼資料： 匯出 generateMetadata({ params, searchParams }: Props) 以提供動態的 title、description 和標準網址（alternates: { canonical: ... }）。
• 結構化資料： 使用 schema-dts（WithContext<T>）注入型別化的 JSON-LD，並包裹在 <script type="application/ld+json"> 中，且將 < 字元跳脫為 \u003c。
• 請參閱 references/seo-structured-data-guide.md 以了解結構定義。

4. 靜態預先渲染 (generateStaticParams)

• 如果頁面位於 [locale] 動態區段（或任何動態區段）之下，且 supported_languages 包含多於一個地區設定，則匯出 generateStaticParams()，針對所有支援的地區設定回傳 { locale }。

5. 即時導航與細粒度 Suspense 下推

• 細粒度載入狀態：將 <Suspense> 下推到特定的動態子元件，以便靜態/快取區段（頁首、英雄區塊、快取的產品資訊）能立即提升至靜態外殼與應用程式外殼中。
• 選擇退出：如果某個區段本質上是動態的，且不需要即時回饋，則可設定 export const instant = false。
• 請參閱 references/streaming-and-boundaries.md 以了解串流模式。

---

工作流程步驟

• 步驟 0：產生實作計畫與核准關卡

  • 讀取 docs/project.json 以及在 lib/routes.ts 中的目標路由定義。
  • 規劃頁面中繼資料、JSON-LD 結構化資料類型、翻譯命名空間以及元件佈局。
  • 如果正在建立主要的新頁面，請向使用者呈現簡潔的實作計畫。

• 步驟 1：填充翻譯字典

  • 在專用的頁面命名空間下，將頁面標題、中繼描述以及頁面內文新增到所有地區設定檔案（messages/en.json、messages/fa.json 等）中。

• 步驟 2：建立伴隨骨架 (loading.tsx)

  • 如果頁面會串流內容或擷取資料，則從 loading.tsx.template 部署 loading.tsx。

• 步驟 3：實作頁面元件 (page.tsx)

  • 部署並自訂 page.tsx.template：
    1. 定義非同步 props 介面（params: Promise<{ locale: string, ... }>、searchParams）。
    2. 匯出 generateMetadata() 以解析動態標題和標準替代網址。
    3. 為在地化/動態路由匯出 generateStaticParams()。
    4. 實作頁面 RSC，組合來自 <new_component_dir>/<page-name>/ 的區段元件。
    5. 渲染 <JsonLd> 結構化資料元件。

• 步驟 4：驗證與完整性檢查

  • 執行頁面驗證腳本：
    • Windows (PowerShell)：

      pwsh .agents/skills/nextjs-page-dev/scripts/verify-page.ps1 -RoutePath <route_dir>
      

    • Linux / macOS (Bash)：

      bash .agents/skills/nextjs-page-dev/scripts/verify-page.sh <route_dir>
      

  • 確保沒有 TypeScript 錯誤或缺少字典的錯誤。

• 步驟 5：同步實作計畫檢查清單

  • 在 docs/plan/05-pages-and-components.md 中，將已完成頁面基礎架構項目（page.tsx、loading.tsx、error.tsx、generateMetadata、JSON-LD Schema、generateStaticParams()）標記為已完成。
  • 如果此頁面的所有子元件檢查清單與頁面基礎架構任務皆已完成，請將父層頁面項目標記為已完成（- [x]）。