BIGboss248/nextjs-wordpress

Next.js WooCommerce 整合 (nextjs-woocommerce)

建構、查詢並整合 Next.js App Router 應用程式與無頭 WooCommerce 後端（透過 WPGraphQL、WooGraphQL 與 JWT 認證）的操作手冊與檢查清單。

---

先決條件與文件參考

• 以 App Router 與 TypeScript 初始化的 Next.js 14+ 專案。
• 已安裝 WPGraphQL、WooGraphQL 與 wp-graphql-jwt-authentication 的活躍 WooCommerce 後端。
• 完整的 API 綱要與 Next.js 程式碼模式，請查閱 nextjs-woocommerce-reference.md。
• 可重複使用的資料擷取客戶端實作，請參閱 woocommerce-fetcher.ts。

---

逐步實作檢查清單

flowchart TD
    S1["1. 環境與客戶端設定"] --> S2["2. 公開產品目錄 (ISR/SSG)"]
    S2 --> S3["3. 使用者認證 (JWT + Cookie)"]
    S3 --> S4["4. 受保護的個人資料與訂單歷史"]
    S4 --> S5["5. 購物車階段與本地結帳橋接"]

階段 1：環境與客戶端設定

• 設定環境變數：
  • 將 NEXT_PUBLIC_WORDPRESS_API_URL=https://your-store.com/graphql 加入 .env.example 與 .env.development。
  • 新增 NEXT_PUBLIC_WORDPRESS_URL=https://your-store.com 作為結帳重新導向使用。
• 建立通用擷取器：
  • 實作 woocommerce-fetcher.ts 以支援 ISR 快取與認證標頭。

階段 2：公開產品目錄與分類法

• 分類導覽：查詢 productCategories 並設定 hideEmpty: true，用於頁首與分類選單。
• 產品列表頁：使用聯集片段 (... on SimpleProduct、... on VariableProduct) 查詢 products，並設定 next: { revalidate: 300, tags: ['products'] }。
• 產品詳細頁面：透過 generateStaticParams() 查詢所有產品 slug，預先渲染動態路由 (app/products/[slug]/page.tsx)。

階段 3：JWT 認證管道

• 登入 Mutation：實作 Server Action 執行 login(input: { username, password })。
• Cookie 儲存：將回傳的 authToken 儲存在安全的 HttpOnly cookie (auth_token) 中。
• Session 綁定：若客戶端回傳 sessionToken，則儲存在 wc_session cookie 中。
• 登出：清除認證 cookie。

階段 4：受保護的使用者資料與訂單

• 客戶個人資料：以 Authorization: Bearer <authToken> 查詢 viewer { id name email }。
• 訂單歷史：以 cache: 'no-store' 查詢 customer { orders { nodes { id orderNumber total status } } }。

階段 5：購物車管理與結帳策略

• 購物車狀態：在 addToCart mutations 回傳時捕捉並持續保存 woocommerce-session 標頭。
• 本地結帳橋接：
  • 將使用者重新導向至 https://your-store.com/checkout 以利用原生的 WooCommerce 付款閘道（例如 ZarinPal、Mellat、Stripe）、區域物流與合規標章，而無需重新撰寫自訂閘道。

---

邊緣案例與已知陷阱

1. 靜態 vs. 動態效能降級：在根佈局或產品頁面讀取 cookie 會使 Next.js 切換為全 SSR 動態模式。僅在 Server Action、Route Handler 或隔離的帳戶儀表板子樹 (app/account/...) 中讀取認證 cookie。
2. 多型片段：直接查詢如 products { nodes { price } } 會在 WooGraphQL 中驗證失敗。請務必將價格與變體包裝在 ... on SimpleProduct 與 ... on VariableProduct 中。
3. Session 遺失：在新增項目至購物車時，若未重新傳送 woocommerce-session 標頭，每次 mutation 都會建立一個新的空購物車。
4. GraphQL 端點的 CORS：確保 WordPress 針對您的 Next.js 網域傳送 Access-Control-Allow-Origin 與 Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session 標頭。

---

驗證與上線前測試

• pnpm build 成功執行並靜態產生產品頁面。
• 測試登入表單是否正確發放 auth_token 並重新導向至儀表板。
• 使用有效 token 時，帳戶頁面能正確顯示客戶詳細資料與訂單列表。
• 加入購物車功能能在多次客戶端請求中更新購物車項目數量。