Next.js + Cloudflare Workers Split Architecture MVP PRD

• 01 December 2025
• Next.js,
• Cloudflare Workers,
• E-commerce,
• Edge Computing,
• Cloudflare,
• Vercel,
• AI,
• LangChain,
• PRD,
• Ian Chou

Product Requirements Document (PRD)

Project Name: Next.js EC Site MVP (Cost-Optimized Edition)
Version: 3.0 (Split Architecture)
Date: 2025-12-01

1. 專案概要 (Project Overview)

本專案旨在建立一個「極致成本效益」與「AI 智慧營運」兼具的電子商務平台。為了嚴格控制營運成本，我們將Storefront (前端) 與 API (後端邏輯) 完全分離。前端使用 Next.js (Static Export) 部署於 Cloudflare Pages，後端業務邏輯由輕量級的 Cloudflare Workers 處理，僅將高運算需求的 AI 部分保留在 Vercel。

• 目的：提供中、小型企業線上銷售，支援國際信用卡付款。
• 目標平台：桌機 + 手機（RWD）。
• 核心策略：
  • 分離架構 (Split Architecture)：Frontend (Pages) 與 Backend (Workers) 分離，精確控制資源消耗。
  • 成本優先 (Cost-First)：主要流量走 Cloudflare 免費/低價方案，避免 Vercel 流量費用。
  • AI 驅動 (AI-Driven)：僅在後台管理時使用 Vercel AI SDK。
• 關鍵優勢：
  • 極低成本：前端為純靜態檔案 (Static Assets)，API 為 Serverless Workers，大幅降低 Server 成本。
  • 極速體驗：前端由 Cloudflare CDN 派發，API 在 Edge 執行。
  • 風險分散：前後端解耦，單一服務故障不影響整體架構。

MVP 階段劃分 (Phase 1 vs Phase 2)

2. 系統架構與技術堆疊 (System Architecture & Stack)

2.1 架構圖解 (Architecture Flow)

本專案採用 「雙入口、單核心」 的安全架構，將一般訪客與管理員的流量物理隔離：

1. 訪客通道 (Public)：訪問 www.example.com (Cloudflare Pages)，僅能讀取靜態頁面與呼叫公開 API。
2. 管理通道 (Private)：訪問 Vercel 專屬網域 (如 project-admin.vercel.app)，此處部署了包含 AI SDK 的 Next.js 應用 (SSR)。此網域不對外公開，降低被掃描與攻擊的風險。
3. 核心 API：所有資料讀寫邏輯統一由 Cloudflare Workers 處理，作為唯一的資料守門員。

    graph TD
    %% 定義樣式
    classDef public fill:#d4f1f4,stroke:#333,stroke-width:2px;
    classDef admin fill:#f2e6ff,stroke:#333,stroke-width:2px;
    classDef api fill:#ffebd8,stroke:#333,stroke-width:2px;
    classDef db fill:#e1f7d5,stroke:#333,stroke-width:2px;

    %% 角色
    User((訪客))
    AdminUser((管理員))

    %% 前端層 - 雙入口
    subgraph Public_Zone ["公開區域"]
        Storefront[🛒 靜態商城 Storefront
Next.js Static Export
Cloudflare Pages]:::public
    end

    subgraph Private_Zone ["管理區域"]
        AdminApp[🛡️ 管理後台 + 🧠 AI Copilot
Next.js SSR + Vercel AI SDK
Vercel Private Domain]:::admin
    end

    %% API 層
    subgraph Core_Layer ["核心邏輯層"]
        API[⚡ API Gateway
Hono Framework
Cloudflare Workers]:::api
    end

    %% 資料層
    subgraph Data_Layer ["資料儲存"]
        DB[(🗄️ 資料庫
Neon Postgres)]:::db
    end

    %% 訪客流程
    %% 修正：連接線文字加上雙引號，避免括號報錯
    User -->|"1. 瀏覽"| Storefront
    Storefront -->|"2. 讀取商品/下單 (Client Fetch)"| API

    %% 管理員流程
    %% 修正：連接線文字加上雙引號
    AdminUser -->|"1. 登入後台 (Vercel)"| AdminApp
    AdminApp -->|"2. 管理指令/AI 分析 (Server Fetch)"| API
    
    %% API -> DB
    API <-->|"3. 統一存取資料"| DB

2.2 技術選型 (Tech Stack)

2.3 前端互動策略 (Frontend Interactivity Strategy)

雖然使用 Static Export (output: 'export')，這僅代表 HTML 是預先生成的，React Client Components ('use client') 依然能在瀏覽器端正常運作，提供完整的 SPA 體驗。

針對常見電商功能的實作方式如下：

1. 加入購物車 (Add to Cart)：使用 React Context 或 Zustand 管理全域購物車狀態，資料儲存於 LocalStorage，完全無需伺服器參與。
2. 商品規格切換 (Variant Selector)：使用 useState 控制當前選擇的規格，純前端互動。
3. 會員登入 (Account Dropdown)：
   • 頁面載入後，useEffect 檢查 LocalStorage/Cookie 中的 Token。
   • 若有 Token，顯示會員選單；若無，顯示登入按鈕。
   • 登入動作呼叫 Worker API (/api/login) 驗證並獲取 Token。
4. 結帳表單驗證 (Form Validation)：使用 React Hook Form + Zod 在瀏覽器端進行即時驗證，不需後端。
5. 購物車側欄 (Cart Drawer)：全域 UI State (isCartOpen) 控制顯示/隱藏。
6. 搜尋框建議 (Search Autocomplete)：輸入文字時 (onChange)，Debounce 後呼叫 Worker API (/api/search?q=...) 獲取建議列表。
7. 收藏/喜歡 (Wishlist)：點擊時呼叫 API 更新資料庫，並更新前端 State。
8. 導覽列/選單互動 (Navigation)：純 CSS Hover 或 React State 控制。

結論：Static Export 不會限制這些功能，反而因為將互動邏輯移至 Client 端，配合 CDN 派發，能提供更流暢的使用者體驗。

3. 使用者流程 (User Flows)

• 訪客：瀏覽商品、加入購物車，結帳時呼叫 API Worker。
• 管理者 (Admin)：透過前端介面觸發 API Worker 進行管理，或觸發 AI 分析。

3.1 一般訪客 (Shopper)

1. 瀏覽：訪問 Cloudflare Pages 上的靜態 Next.js 頁面 (CDN 快取，零運算成本)。
2. 庫存檢查：Client Component (React) 呼叫 https://api.yourdomain.com/products (Worker) 獲取即時庫存。
3. 結帳：
   • 前端呼叫 https://api.yourdomain.com/checkout (Worker)。
   • Worker 建立 Stripe Session 並回傳 URL。
   • 前端導向 Stripe 付款。
   • Stripe Webhook 回呼 https://api.yourdomain.com/webhook (Worker) 更新 Neon 庫存。

3.2 管理者 (Admin) - 進銷存管理 & AI Copilot

1. 資料同步 (Sync)：
   • 前端呼叫 https://api.yourdomain.com/sync。
   • Worker 接收資料並更新 Neon 資料庫。
2. AI 進銷存 Copilot：
   • 管理員在 Chat 介面輸入指令。
   • 前端呼叫 https://api.yourdomain.com/analyze (Worker)。
   • Worker 作為 Proxy，將請求轉發給 Vercel AI Backend (隱藏 Vercel URL)。
   • Vercel AI SDK 解析指令並操作 Neon DB，回傳結果。
   • 這樣設計確保 Vercel 僅在 AI 功能被使用時才被喚醒，平時不處理任何流量。

4. 詳細功能規格 (Functional Specifications)

4.1 資料庫設計 (Neon Postgres Schema)

• Products: id, name, sku, price, stock_quantity
• Orders: id, total_amount, status, stripe_session_id (UNIQUE), created_at
• Analysis_Log: id, ai_suggestion, created_at

4.2 API 介面定義 (Cloudflare Workers - Hono)

所有 API 部署在獨立的 Worker，網域如 api.store.com。

4.3 Vercel AI SDK (AI Service)

• 定位：純粹的 AI 計算節點，不直接對公眾提供服務。
• 觸發：僅接受來自 Cloudflare Workers 的請求 (透過 Secret Key 驗證)。
• 功能：LangChain Agent 邏輯，負責自然語言轉 SQL 操作。

4.4 網站頁面架構 (Frontend - Next.js Static)

1. 首頁 / (SSG)
2. 商品列表頁 /products (SSG + Client Fetch for Price/Stock)
   • 頁面骨架由 SSG 生成。
   • 價格與庫存由 useEffect 呼叫 Worker API 填入，確保靜態頁面也能顯示即時資訊。
3. 商品詳細頁 /products/[slug] (SSG + Client Fetch)
4. 購物車頁 /cart (Client Side Only)
5. 結帳頁 /checkout (Client Side Only)
6. 靜態頁面 (/about, /contact, /policy)

4.5 金流整合 (Stripe)

• 核心變更：
  • 建立 Session 的邏輯移至 Cloudflare Workers。
  • Webhook 處理移至 Cloudflare Workers。
  • 前端僅負責收集資料並 POST 到 Worker。

5. 部署與開發流程 (Deployment & DevOps)

5.1 環境變數配置 (.env)

Cloudflare Workers (wrangler.toml):

[vars]
NEON_URL = "postgres://..."
STRIPE_SECRET_KEY = "sk_..."
VERCEL_AI_URL = "https://your-vercel-project.vercel.app/api/ai"
VERCEL_SECRET = "shared_secret"

Next.js (Frontend):

NEXT_PUBLIC_API_URL=https://api.yourdomain.com

Vercel (AI Backend):

OPENAI_API_KEY=...
NEON_URL="postgres://..."
VERCEL_SECRET="shared_secret"

5.2 部署指令

1. API Gateway (Cloudflare Workers)

   # 使用 Hono 或是原生 Worker
   cd workers-api
   npm install
   npx wrangler deploy

2. Frontend (Next.js -> Cloudflare Pages)

   # next.config.js 設定 output: 'export'
   npm run build
   # 生成 out/ 目錄
   npx wrangler pages deploy out --project-name=my-storefront

3. AI Backend (Vercel)

   cd ai-service
   vercel --prod

6. 商業與運維優勢 (Business & Ops Benefits)

1. 極致成本控制 (Cost Control)：
   • Vercel 費用最小化：Vercel 僅作為「AI 運算單元」，不處理任何一般流量。一般訪客瀏覽、下單完全不經過 Vercel，避開 Vercel 的流量與 Function 呼叫計費。
   • Cloudflare 優勢：Pages 託管靜態檔案免費，Workers 費用極低 (前 10 萬請求免費，之後極便宜)。
2. 效能最佳化：
   • 靜態頁面 (Static Assets) 透過 Cloudflare 全球 CDN 快取，載入速度最快。
   • API 邏輯在 Edge 執行，無 Cold Start 問題 (相比 Vercel Serverless)。
3. 架構清晰：
   • 前端專注 UI，後端專注邏輯。更換前端框架 (如改回 Astro 或 Vue) 不需重寫 API。

7. 潛在風險與解決方案

• 風險：CORS (跨來源資源共用) 問題。
  • 解法：Worker API 必須設定正確的 CORS Header (Access-Control-Allow-Origin: https://your-store.pages.dev)。Hono 框架內建 CORS middleware，易於設定。
• 風險：資料一致性 (Client Fetch)。
  • 解法：由於是靜態頁面 + Client Fetch，可能會有一瞬間的 Loading 狀態。建議使用 React Suspense 或 Skeleton Screen 提升 UX。

其它建議

1. 使用 Hono 框架：

   • 強烈建議在 Cloudflare Workers 使用 Hono。它輕量、支援 TypeScript、語法類似 Express，且對 Web Standards 支援極佳，非常適合構建這種 Edge API。

2. 安全性 (API Security)：

   • 因為 API 獨立暴露，務必限制 Access-Control-Allow-Origin 僅允許你的前端網域。
   • 對於 /sync 或 /analyze 等管理端 API，務必檢查 Header 中的 Admin Secret 或 Token。

3. Drizzle ORM 共用 Schema：

   • 建議將 Drizzle Schema 抽離成獨立的 shared-schema package 或資料夾，讓 Workers (API) 與 Vercel (AI) 都能引用同一份定義，確保資料庫操作一致。

• ← Previous
  白皮書：《2025 電商技術革命：從 SEO 到 GEO，打造 Cloudflare 與 Vercel 驅動的現代化光速商店》
• Next →
  Next.js EC Site MVP - Monorepo Architecture Documentation (Bun Edition)