dee0917/commercecraft-agent-skill

全自動純前端頂級電商獨立站建站引擎 (Auto E-Commerce Frontend Engine)

核心理念：極致視覺美學，硬核工程架構，100% 前端閉環體驗，零外部依賴。

本技能整合成熟 DTC 電商模式與現代前端工程實務，專注於提供商業級、零佔位符 (Zero Placeholders)、具備真實購物與結帳狀態機的現代化純前端電商體驗。

執行語言規範：

• 品牌名稱、商品標題、規格參數、UI 文案 → 全英文 (English Only)，呈現國際品牌質感。
• 開發日誌、進度報告、技術說明與用戶互動 → 繁體中文 (Traditional Chinese)。
• 代碼中之變數、函數、介面定義 → 英文駝峰 (camelCase / PascalCase)，絕對禁止拼音命名。

---

🤖 五大虛擬角色與技能矩陣 (Agent Team Architecture)

在執行建站流程時，AI 代理人將切換為 5 個專業角色，依序推動與相互校驗：

角色 (Role)	核心職責	核心技能標籤 (Skills)
1. Project Orchestrator	品牌定位、類別選定、執行計畫排程與跨階段協調	prd, brainstorming, executing-plans, writing-plans
2. Chief Creative Director	品牌 Vibe 氛圍定義、色彩對比、字體系統與高質感排版	ui-ux-pro-max, brand-guidelines, canvas-design, frontend-design
3. Lead Full-Stack Architect	TypeScript 嚴格介面、Zustand 狀態機、RWD 組件與路由實作	web-artifacts-builder, frontend-design, react-best-practices, tailwindcss
4. Content Strategist	專業商品描述、故事文案、SEO 關鍵字與顧客評價設計	content-research-writer, internal-comms, brand-guidelines, doc-coauthoring
5. QA & Compliance	零佔位符稽核、Console 錯誤排查、Build 驗收與 7 層門檻檢查	verification-before-completion, webapp-testing, systematic-debugging, audit

---

🚀 全生命週期執行流程 (Lifecycle Phases)

用戶發起: "幫我生成一個 [類別/風格] 的電商網站"

┌─ Phase 0: 零容忍守則與心理學規則載入 (P0)
│  ├─ 📖 讀取 references/anti-patterns.md (18 條零容忍規範)
│  └─ 📖 讀取 references/ux-psychology-ecommerce.md (CRO 心理學原則)
│
├─ Phase 1: 創意種子與設計系統生成 (Creative & System Generation)
│  ├─ 🎲 確定品牌主題 (如：Minimal Desk Aesthetics, Luxe Aromatherapy, Tech Gear)
│  ├─ 🎨 執行 Creative Director: 決定色彩盤 (60-30-10 法則) 與字體 (Display / Body)
│  ├─ ✍️ 執行 Content Strategist: 生成品牌核心標語與 8~12 項高擬真商品規格數據
│  └─ 📝 輸出專案 PRD 摘要與設計決策至 docs/DESIGN_DECISIONS.md
│
├─ Phase 2: 純前端工程搭建 (Vite + React + TS + Tailwind)
│  ├─ 🏗️ 初始化專案骨架 (Vite React-TS)
│  ├─ 📦 安裝核心依賴: zustand, react-router-dom, lucide-react, clsx, tailwind-merge, framer-motion, canvas-confetti
│  ├─ 📐 導入 templates/ecommerce-types.ts 確保強型別約束
│  └─ 🛒 實作狀態層 (src/store/useCartStore.ts) 具備 LocalStorage 持久化
│
├─ Phase 3: 11 頁完整電商路由實作 (100% Complete Routes)
│  ├─ 🏠 Layer A (核心購物閉環): Home, Shop, ProductDetail, CartDrawer, Checkout, OrderSuccess
│  ├─ 👤 Layer B (用戶信任中心): Profile, OrderHistory
│  └─ 📜 Layer C (合規與信任頁面): FAQ, ShippingPolicy, ReturnsRefunds, About
│
├─ Phase 4: CRO 心理學強化與視覺昇華
│  ├─ ⏳ 注入稀缺性標籤 (Scarcity: "Only 3 units left!")
│  ├─ 🚚 實作免運門檻差額進度條 ("Add $X more to unlock Free Shipping")
│  ├─ ⭐ 嵌入真實顧客星級評價與購買動態 (Social Proof)
│  ├─ 🏷️ 注入 Schema.org (Product, Offer) JSON-LD 結構化資料
│  └─ 🖼️ 配置高清晰 Unsplash 商業寫真圖片 (禁絕模糊佔位符)
│
└─ Phase 5: 品質驗收與一鍵交付 (Quality & Delivery Gate)
   ├─ 🔨 執行 npm run build (確保 0 TypeScript 錯誤、0 構建警告)
   ├─ 🔍 執行 7 層品質門檻檢驗 (Zero Mock, Zero Broken Links)
   └─ 🚀 交付前端預覽與 Vercel 一鍵部署指引

---

📋 11 頁全功能路由規範 (Page Requirements)

所有生成之網站必須具備下列 11 頁完整路由，絕不允許空頁面或 404：

1. 首頁 (/)：

   • Hero 視覺橫幅（高衝擊力大圖、強烈召喚行動 CTA "Shop The Collection"）。
   • 權威信任標章（Free Shipping、30-Day Guarantee、256-Bit SSL、Ethical Craft）。
   • 精選推薦商品瀑布流 (Featured Products Grid)。
   • 分類快速入口 (Shop by Categories)。
   • 品牌故事區塊 (Brand Ethos)。
   • 顧客真實見證 (Social Proof Testimonials)。
   • 電子報訂閱區 (Newsletter Signup with discount incentive)。

2. 商品目錄 (/shop)：

   • 多維篩選器：分類 Filter、價格區間 Slider、標籤過濾。
   • 即時排序功能：熱門度、價格由低到高、價格由高到低、最新上架。
   • 即時關鍵字搜尋框 (Instant Client Search)。
   • 空搜尋防禦狀態 (Empty State with reset filters button)。

3. 商品詳情頁 (/product/:id)：

   • 多角度縮圖預覽切換 (Image Gallery)。
   • 規格選擇器：尺寸 (Size)、顏色 (Color)、款式 (Variant)。
   • 庫存緊迫性提示（例如庫存 < 5 時顯示琥珀色警示）。
   • 數量加減調節器。
   • 「Add to Cart」（滑入購物車抽屜）與「Buy Now」（直通結帳）雙按鈕。
   • 頁籤分頁：詳細規格 (Specifications)、配送與退換說明 (Shipping)、顧客真實評價 (Reviews)。
   • 相關商品推薦 (Recommended Products)。
   • Schema.org JSON-LD 注入。

4. 側邊購物車抽屜 (CartDrawer)：

   • 點擊全站 Header 購物車圖示或點擊 Add to Cart 時平滑滑入 (Framer Motion / Transition)。
   • 免運金額門檻差額即時計算進度條（如滿 $100 免運）。
   • 商品清單：縮圖、品名、選定規格、數量增減、即時刪除。
   • 折扣碼 (Promo Code) 兌換框（內建如 WELCOME10 即時折抵 10%）。
   • 價格彙整：小計 (Subtotal)、折扣 (Discount)、預估運費 (Shipping)、總金額 (Total)。
   • 直達結帳按鈕 (Proceed to Checkout)。

5. 結帳中心 (/checkout)：

   • 3 步驟結帳 UI：
     1. 聯絡與寄送資訊 (Shipping Details)：姓名、Email、收件地址、電話。
     2. 配送方式選擇 (Shipping Method)：Standard ($0 ~ $5)、Express ($15)。
     3. 付款方式模擬 (Payment Method)：信用卡模擬輸入（含自動格式化、安全圖示）、Apple Pay / PayPal 快速結帳選項。
   • 右側/下方即時訂單摘要卡片 (Order Summary Sticky Card)。
   • 防重複點擊、表單欄位即時驗證。

6. 訂單完成頁 (/order-success)：

   • 綠色成功勾選動畫與慶祝彩花效果 (canvas-confetti)。
   • 隨機生成的專屬訂單編號（如 #ORD-2026-89412）。
   • 完整訂單摘要清單、收件人資料與預計送達日期。
   • 「Continue Shopping」返回按鈕。

7. 訂單追蹤與歷史 (/orders)：

   • 輸入訂單編號或 Email 查詢模擬訂單進度條（Confirmed → Processing → Shipped → Delivered）。

8. 會員與收藏 (/profile)：

   • 模擬用戶基本資料、心願清單 (Wishlist) 快速查看。

9. 常見問題 (/faq)：

   • 折疊手風琴組件 (Accordion)，包含訂購、運送、退換、材質保養等熱門問題。

10. 運送政策 (/shipping)：

    • 包含國內外運費費率表、各國配送工作天數、關稅說明。

11. 退換貨政策與品牌故事 (/returns & /about)：

    • 清楚陳述 30 天退換保證條款、退貨三步驟流程與品牌創辦初心。

---

🧠 電商心理學與轉化率 (CRO) 強制實作指南

每次生成的網站必須融入下列心理學機制（詳細定義參閱 references/ux-psychology-ecommerce.md）：

1. 席克定律 (Hick's Law)：
   • 結帳表單預設精簡，減少不必要的非必填欄位。
   • 導航列主選單不超過 5 個一級項目。
2. 錨定效應 (Anchoring Effect)：
   • 特價商品並列顯示原價刪除線（如 ~~$120.00~~ $89.00）並標註節省金額標籤 Save $31。
3. 稀缺性與緊迫感 (Scarcity & Urgency)：
   • 詳情頁動態隨機顯示 "Only 2 items left at this price"。
   • 結帳頁面標註 "Reserved for your cart for 10:00 minutes"（可選計時器）。
4. 社會認同 (Social Proof)：
   • 首頁與詳情頁標記真實購買者驗證徽章 (Verified Buyer)。
   • 商品列表卡片平均評分（如 ★ 4.9 (128 reviews)）。
5. 損失厭惡 (Loss Aversion)：
   • 購物車免運進度條動態提醒：「只差 $12 即可享受全館免運！」。

---

🛠️ 狀態管理架構規範 (Zustand + LocalStorage)

採用解耦且防抖的 Zustand Store，確保刷新頁面後購物車數據不流失：

// src/store/useCartStore.ts 規範範本
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { CartItem, Product } from '../types';

interface CartState {
  items: CartItem[];
  isOpen: boolean;
  promoCode: string | null;
  discountRate: number;
  openCart: () => void;
  closeCart: () => void;
  addItem: (product: Product, quantity?: number, selectedVariant?: string) => void;
  removeItem: (itemId: string) => void;
  updateQuantity: (itemId: string, quantity: number) => void;
  applyPromoCode: (code: string) => { success: boolean; message: string };
  clearCart: () => void;
  getSubtotal: () => number;
  getTotal: () => number;
}

---

🛡️ 交付品質防線 (7 層驗收門檻)

在向用戶提交成果前，QA 角色必須逐項驗證通過：

1. 0 破圖 (Zero Broken Images)：所有圖片 URL 均能正常載入且尺寸適配，具備 loading="lazy" 與 alt 屬性。
2. 0 死連結 (Zero Broken Links)：全站導航、頁尾連結、按鈕均可點擊且跳轉至對應 11 頁路由。
3. 0 佔位符 (Zero Placeholders)：禁絕出現 Lorem Ipsum、Product 1、$0.00 等敷衍文字，所有文案必須吻合該品牌調性。
4. 購物車全閉環 (Cart Loop Completed)：加入購物車 → 抽屜滑入 → 修改數量金額聯動 → 輸入優惠券折抵 → 結帳送出 → 跳轉 Order Success 取得訂單編號。
5. RWD 響應式保證：手機 (375px)、平板 (768px)、桌面 (1280px+) 均無水平溢出跑版。
6. SEO 結構化：商品詳情頁輸出正確之 application/ld+json (Schema.org Product)。
7. 生產構建驗證 (Production Build)：執行 npm run build 毫無錯誤，產出 dist/ 目錄。