Astro EC Site MVP (Edge + AI Hybrid) 產品需求文件 PRD

• 01 December 2025
• Astro,
• E-commerce,
• Edge Computing,
• Cloudflare,
• Vercel,
• AI,
• LangChain,
• PRD,
• Ian Chou

Product Requirements Document (PRD)

Project Name: Astro EC Site MVP (AI-Enhanced Edition)
Version: 2.0 (Edge + AI Hybrid)
Date: 2025-12-01

1. 專案概要 (Project Overview)

本專案旨在建立一個結合「極速購物體驗」與「AI 智慧進銷存」的電子商務平台。透過 Cloudflare 邊緣網絡確保全球訪客的載入速度 (Sub-second load time)，並整合 Vercel AI SDK 進銷存 Copilot 做網站後台管理。

• 目的：提供小型商品（約 50 個 SKU）線上銷售，支援國際信用卡付款。
• 目標平台：桌機 + 手機（RWD）。
• 核心策略：多雲協作 (Multi-Cloud)、邊緣優先 (Edge-First)、AI 驅動 (AI-Driven)。
• 關鍵優勢：
  • 極速體驗：靜態頁面位於 Edge (Cloudflare)，資料層使用 Serverless Postgres (Neon) 提供穩定低延遲的交易存取。
  • 智慧營運：利用 LangChain Agent 做網站後台管理。
  • 成本效益：平時營運極低成本 (Static/Workers)，AI 運算僅在處理後台工作時按需付費。

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

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

2.1 架構圖解 (Architecture Flow)

graph TD
    User[訪客/管理員] -->|HTTPS| CF_Pages[Astro Frontend
Cloudflare Pages]

    subgraph Cloudflare Ecosystem
        CF_Pages -->|Fetch /api/sync| CF_Worker[Cloudflare Workers
Gateway API]
        CF_Pages -->|Fetch /api/analyze| CF_Worker
    end

    subgraph Neon Cloud
        NeonDB[(Neon Serverless
Postgres)]
    end

    subgraph Vercel Ecosystem
        CF_Worker -->|Proxy Request| Vercel_AI[Vercel AI SDK
LangChain]
    end

    CF_Worker <-->|SQL over HTTP| NeonDB
    Vercel_AI <-->|SQL over HTTP| NeonDB

2.2 技術選型 (Tech Stack)

• Frontend / SSR 實作：Astro（最新穩定版）、TypeScript、Tailwind CSS。
• 金流實作：Stripe Checkout / Payment Element、PayPal Checkout（Smart Payment Buttons）。

3. 使用者流程 (User Flows)

• 訪客：瀏覽商品、加入購物車，可不註冊完成結帳。
• 管理者 (Admin)：管理 SKU 價格與庫存、維護可配送地區設定與 AI Copilot 操作權限。

3.1 一般訪客 (Shopper)

1. 瀏覽：訪問 Cloudflare Pages 託管的靜態頁面 (極速)。
2. 庫存檢查：進入商品頁時，Astro (SSR) 或 Client 透過 Workers API 查詢 Neon Postgres 實時庫存。
3. 結帳：Stripe/PayPal 結帳 -> Webhook 觸發 Workers -> 扣除 Neon 庫存。

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

1. 資料同步 (Sync)：
   • 管理員上傳最新的商品 JSON 或 Excel。
   • 前端呼叫 /api/sync。
   • Workers 接收資料並更新 Neon 資料庫。
2. AI 進銷存 Copilot（列表頁）：
   • 管理員在部署於 Vercel 的 listings 頁面查看 Neon Postgres 中的商品庫存與價格。
   • 可直接在表格中編輯 stock、price 等欄位，由後端透過 Drizzle + Neon 將變更寫回資料庫。
3. AI 進銷存 Copilot（Chat 介面）：
   • 管理員在 Chat 介面輸入自然語言指令（例如：「把夏季系列庫存 +20」、「把 SKU123 價格改成 1290」）。
   • Vercel AI SDK 將指令解析為結構化變更（要修改的 SKU、欄位與新值），並呼叫 Drizzle + Neon 套用到資料庫。
   • 系統回傳本次變更摘要（被修改的 SKU、欄位與新值），方便管理員在手機或桌機上快速確認。

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 (AI 給出的建議文字), created_at

4.2 API 介面定義 (Workers Route)

所有 API 統一由 Cloudflare Workers 網域提供 (例如 api.yourbrand.com 或同網域路由)，解決跨域問題 (CORS)。

4.3 Vercel AI SDK：進銷存 Copilot 整合

• 觸發點：由部署在 Vercel 的後台頁面（listings / Chat）透過 Route Handler 或 API Route 呼叫。
• 權限：僅限登入的管理者帳號，並可搭配 Bearer Token (雙方約定的 Secret) 防止惡意呼叫消耗 Token。
• 邏輯：
  1. 接收管理者從列表或 Chat 介面送出的請求（自然語言或結構化指令）。
  2. 使用 LLM 將自然語言轉換為結構化「變更計畫」（要修改的 SKU、欄位、舊值與新值）。
  3. 連線至 Neon Postgres（透過 @neondatabase/serverless 搭配 drizzle-orm/neon-http），執行對應的 UPDATE/INSERT 操作。
  4. （選用）回寫一筆操作紀錄／摘要到 Analysis_Log 或其他審計表，方便日後追蹤。
  5. 回傳本次變更結果給前端（包含成功修改的 SKU 與欄位），讓管理員在手機或桌機上立即確認。

4.4 網站頁面架構 (Frontend Pages)

1. 首頁 /
   • Hero 區塊（品牌標語 + CTA 按鈕）
   • 精選商品（最多 4–6 個）
   • 優點介紹 / USP
2. 商品列表頁 /products
   • 顯示所有 SKU
   • 支援簡易篩選 / 排序（例如「價格由低到高」）
3. 商品詳細頁 /products/[slug]
   • 商品名稱、圖片、價格、描述
   • 規格／尺寸／顏色（如有）
   • 加入購物車按鈕
4. 購物車頁 /cart
   • 列出商品：名稱、數量、小計
   • 支援：增加 / 減少數量、移除商品
   • 顯示總金額
   • 前往結帳按鈕
5. 結帳頁 /checkout
   • 填寫 Email、收件人姓名、收件地址（若是實體商品）
   • 選擇付款方式：Stripe / PayPal
   • 按下「前往付款」後導向對應金流頁面
6. 訂單結果頁
   • /order/success：付款成功顯示感謝頁，顯示訂單摘要（非敏感資訊）
   • /order/cancel：付款取消或失敗的頁面，提供「回購物車」按鈕
7. 靜態頁面
   • /about：品牌介紹
   • /contact：聯絡方式
   • /policy：隱私權 & 退換貨／退款政策

4.5 商品與購物車

• 購物車功能：
  • 可以從商品列表頁 / 詳細頁加入購物車
  • 可更新數量、刪除單一商品、全部清空
  • 預估小計、稅收（如有）、總金額
  • 購物車資料主要存在 Client Side（LocalStorage）。
  • 庫存驗證時機：
    • /checkout 頁面載入時，前端呼叫 /api/products/validate-cart，傳入購物車明細，由後端即時檢查各商品庫存與價格是否仍有效。
    • 若任一商品庫存不足，立即提示「商品 X 目前缺貨」，引導使用者返回 /cart 調整後再繼續結帳，避免已完成付款卻失敗的體驗。
    • 在建立 Stripe Checkout Session 之前，後端會再對購物車內容做一次庫存驗證，以降低 race condition 風險。

4.6 金流整合 – Stripe

• 整合方式：使用 Stripe 官方 SDK / API 建立 Checkout Session。

• 流程：

  1. 使用者在 /checkout 選擇「Stripe」付款。
  2. 前端把購物車內容 + 使用者資料送到 server（Astro server route / Cloudflare Worker）。
  3. server side 建立 Stripe Checkout Session，帶入 line items、success_url、cancel_url。
  4. 回傳 session URL，前端導向 Stripe Checkout。
  5. Stripe 完成付款後，透過 success_url 導回 /order/success。
  6. 由部署在 Cloudflare 的 Webhook 接收 checkout.session.completed 事件，確認付款成功，若該 stripe_session_id 尚未處理，則寫入 Neon 的訂單紀錄並扣減庫存。

• 交易一致性與 Webhook 冪等性設計：

  • 在 Orders 表加入 stripe_session_id UNIQUE 約束，確保同一個 Stripe Session 只會被寫入一次。
  • Webhook handler 流程：
    • 先以 stripe_session_id 查詢 Orders 是否已存在紀錄，若已存在則直接回應 200 OK，不再重複扣庫存。
    • 若不存在，於單一資料庫操作（或交易）中建立 Orders 紀錄並更新 Products.stock_quantity，確保訂單建立與庫存扣減同步成功或失敗。
  • 這樣即使 Stripe 因暫時錯誤重送 Webhook，也只會對每一筆付款扣庫存一次。

4.7 金流整合 – PayPal

• 整合方式：使用 PayPal Checkout（Smart Buttons）。
• 流程：
  1. 結帳頁載入 PayPal SDK script（使用 client id）。
  2. 在前端渲染 PayPal Button。
  3. 使用者完成 PayPal 付款。
  4. onApprove callback 時可呼叫後端 API 驗證付款（選用）。
  5. 成功後導向 /order/success，失敗或取消則導向 /order/cancel。

4.8 出貨地區控制（Shipment Area Control）

• 可配送地區的設定存放在程式碼庫中，例如：
  • src/config/shipping.ts（TypeScript）
  • 或 src/config/shipping.json
• 管理者（工程師）修改這個檔案後：
  1. 在開發環境用 bun run dev 驗證行為正確。
  2. 將修改 commit 到 Git。
  3. push 至遠端 repo，由 Cloudflare Pages 自動 build & deploy。
• 不實作線上 /admin/shipping 頁面，所有出貨地區調整都透過 repo 內設定檔完成（GitOps 流程）。
• 出貨地區調整開發流程：
  1. 開發環境執行 bun run dev。
  2. 編輯 src/config/shipping.ts 中的 ALLOWED_SHIPPING_ZONES。
  3. 重新整理頁面確認：可配送地區選單與運費計算是否正確，不支援地區是否被擋住。

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

5.1 環境變數配置 (.env)

Cloudflare Pages & Workers:

# 連接 Vercel 的密鑰
VERCEL_SECRET=your_shared_secret_key
# Neon Postgres 連線字串
NEON_URL=postgres://user:[email protected]/db
# Stripe/PayPal Keys
STRIPE_SECRET_KEY=sk_...

Vercel:

# Neon Postgres 連線字串
NEON_URL=postgres://user:[email protected]/db
# AI Provider Keys
OPENAI_API_KEY=...
# 驗證來自 Workers 的請求
VERCEL_SECRET=your_shared_secret_key

5.2 部署指令 (Deployment Guide)

為了在 15 分鐘內完成上線，請依照以下順序：

1. Database (Neon Postgres)

   # 在 Neon 後台建立專案與資料表，或透過 psql 套用 schema
   psql $NEON_URL < ./schema.sql

2. API Gateway (Workers)

   # 在 workers 目錄下部署，並確保已設定 NEON_URL secret
   npx wrangler secret put NEON_URL
   npx wrangler deploy

3. AI Backend (Vercel)

   # 部署 Vercel 專案並設定 NEON_URL / OPENAI_API_KEY
   vercel --prod

4. Frontend (Astro -> CF Pages)

   git push origin main
   # Cloudflare Pages 自動偵測並部署

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

1. 高可用性 (High Availability)：
   • 若 Vercel (AI) 掛點，消費者依然可以正常瀏覽商品與結帳 (Core flow on Cloudflare)，僅後台分析功能暫停。
2. 極致成本控制：
   • 靜態流量走 Cloudflare 免費/低價額度，交易資料走 Neon Serverless Postgres 的免費額度與按量計費模型。
   • 昂貴的 AI Compute Time (Vercel Function duration) 只有在管理員按「分析」時才產生。
3. 專業形象：
   • 單一網域 (Single Domain) 體驗，不會出現 api.vercel.app 這種第三方網址，提升品牌信任度。

7. 潛在風險與解決方案

• 風險：Neon 作為外部雲端 Postgres 服務，若發生區域性故障或連線問題，可能影響交易流程。
  解法：選擇具備高可用性的 Neon 方案，並在 Workers 層實作重試與降級策略（僅允許瀏覽，不允許新訂單）。
• 風險：Cloudflare Workers 與 Neon 所在 Region 之間的網路延遲。
  解法：選擇接近主要客群的 Neon Region，並對熱門查詢實作簡單 Cache API，減少反覆查詢資料庫。

其它建議

1. API 安全性：

   • 雖然 /api/analyze 是內部功能，但因為暴露在公網，建議在 Request Header 加上簡單的 Admin Password 驗證，或者檢查 Cloudflare Access 的 Token，避免被路人亂打 API 導致你的 Vercel 帳單爆炸。

2. Drizzle ORM 是關鍵：

   • 因為你在兩個地方 (Workers, Vercel) 都要操作同一個 Neon Postgres，強烈建議把 Database Schema 定義成一個共用的 TypeScript Package，或者兩邊 copy 一份一樣的 schema.ts。使用 Drizzle ORM（搭配 neon-http）可以讓你用 TypeScript 操作 SQL，開發體驗會好非常多。

3. 保持 Workers 輕量化：

   • 千萬不要在 Workers 裡面跑複雜的迴圈或資料處理。Workers 的 CPU 時間有限 (預設 10ms/50ms)。邏輯是：Workers 負責搬運 (I/O)，Vercel 負責思考 (Compute)。你的架構圖已經完美體現了這一點，執行時請務必堅持這個原則.

4. 法律與合規（Stripe / PayPal 審核）：

   • 在 footer 加上 /policy, /privacy, /terms 等靜態頁面連結。
   • 清楚寫明退款期限、聯絡方式，降低金流審核風險。

5. 交易郵件通知（Transactional Emails）：

   • 建議開啟 Stripe Dashboard 中「Email customers about successful payments」，由 Stripe 代寄收據。
   • 出貨通知在 MVP 階段可先由人工 Email 寄送，之後再視需要自動化。

6. Cloudflare Pages _routes.json 優化：

   • 在 public/_routes.json 明確標註哪些是靜態資源、哪些走 Workers，節省運算資源並提升圖片載入速度。

7. 測試環境 vs 生產環境（Env Vars）：

   • 在 Cloudflare Pages 區分 Production / Preview 環境變數：
     • Production：Stripe Live Keys
     • Preview：Stripe Test Keys
   • 避免測試時誤用正式金流，或上線後仍使用測試 Key。

8. 圖片處理（Image Optimization）：

   • 建議善用 Astro <Image /> 元件或類似機制，自動產生多尺寸 WebP/AVIF，提升行動端載入速度。

9. 客服入口（Contact）：

   • MVP 階段可先使用 mailto:[email protected] 或連結至既有的聯絡渠道（例如 LINE / WhatsApp），之後再視需求擴充成表單 + 後端服務。

10. Neon 連線效能：

    • 使用 @neondatabase/serverless 的 HTTP driver，在 Workers / Vercel runtime 中共用初始化好的 Neon client，避免每個請求重新建立多個連線。
    • 後續若官方提供連線池或最大併發設定，應依實際流量調整，以避免 Workers 併發過高時觸及 Neon 資源限制。

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