跳至主要内容

US-303: 客戶訂單歷史與統計

User Story​

作為 店員 我想要 能夠查看客戶的訂單歷史與消費統計 以便 了解客戶的購買習慣並提供更好的服務

驗收標準 (Acceptance Criteria)​

Scenario 1: 查看客戶詳情頁（基本資訊）​

  • Given 我是已登入的店員
  • And 系統中有客戶「王小明」（編號: ABC-CUST-000001）
  • And 該客戶累計消費 $8,500，共 12 筆訂單
  • When 我點擊客戶列表中的「王小明」
  • Then 系統應導航至客戶詳情頁
  • And 頁面應顯示以下基本資訊：
    • 客戶編號: ABC-CUST-000001
    • 客戶姓名: 王小明
    • 客戶等級徽章: VIP
    • 客戶狀態: 啟用
    • 電話: 0912-345-678
    • Email: wang@example.com
    • 註冊日期: 2025-01-15
    • 最後消費日期: 2025-10-31

Scenario 2: 查看訂單歷史列表（最近 10 筆）​

  • Given 我在客戶「王小明」的詳情頁
  • And 該客戶共有 12 筆訂單
  • Then 訂單歷史區塊應顯示最近 10 筆訂單
  • And 每筆訂單應顯示：
    • 訂單編號
    • 訂單日期
    • 訂單金額
    • 訂單狀態（已完成/進行中/已取消）
  • And 訂單應依日期降序排列（最新訂單在上）
  • And 區塊底部應顯示「查看所有訂單」連結

Scenario 3: 查看所有訂單​

  • Given 我在客戶「王小明」的詳情頁
  • And 訂單歷史區塊顯示「查看所有訂單」連結
  • When 我點擊「查看所有訂單」連結
  • Then 系統應導航至訂單列表頁
  • And 訂單列表應自動套用過濾條件「客戶: 王小明」
  • And 列表應顯示該客戶的所有訂單（包含已取消的訂單）

Scenario 4: 點擊訂單進入詳情頁​

  • Given 我在客戶「王小明」的詳情頁
  • And 訂單歷史列表顯示訂單「ABC-20251031-0001」
  • When 我點擊訂單編號「ABC-20251031-0001」
  • Then 系統應導航至訂單詳情頁
  • And 訂單詳情頁應顯示完整的訂單資訊

Scenario 5: 查看消費統計（基本指標）​

  • Given 我在客戶「王小明」的詳情頁
  • Then 消費統計區塊應顯示以下指標：
    • 總訂單數: 12 筆
    • 累計消費金額: $8,500
    • 平均訂單金額: $708（$8,500 / 12）
    • 最後消費日期: 2025-10-31

Scenario 6: 查看最常購買的商品（Top 3）​

  • Given 我在客戶「王小明」的詳情頁
  • And 該客戶最常購買的商品為：
    1. 玫瑰花束（12 朵）- 購買 5 次
    2. 百合花束（6 朵）- 購買 3 次
    3. 祝賀花籃 - 購買 2 次
  • Then 消費統計區塊應顯示 Top 3 商品列表
  • And 每個商品應顯示：
    • 商品名稱
    • 購買次數
    • 佔比（購買次數 / 總訂單數）

Scenario 7: 查看消費趨勢圖表（近 12 個月）​

  • Given 我在客戶「王小明」的詳情頁
  • And 該客戶近 12 個月的消費記錄如下：
    • 2024-11: $500
    • 2024-12: $800
    • 2025-01: $1,200
    • ...
  • Then 消費統計區塊應顯示折線圖
  • And 圖表 X 軸為月份（近 12 個月）
  • And 圖表 Y 軸為消費金額
  • And 滑鼠 Hover 時顯示該月的詳細金額

Scenario 8: 查看客戶備註（含歷史記錄）​

  • Given 我在客戶「王小明」的詳情頁
  • And 該客戶有 2 筆備註記錄：
    1. 2025-10-01: 「喜歡粉色玫瑰」（記錄人: 店員 A）
    2. 2025-09-15: 「需提前一天確認配送時間」（記錄人: 店員 B）
  • Then 備註區塊應顯示所有備註記錄
  • And 每筆備註應顯示：
    • 備註內容
    • 記錄時間
    • 記錄人
  • And 備註應依時間降序排列（最新備註在上）

Scenario 9: 新增客戶備註​

  • Given 我在客戶「王小明」的詳情頁
  • When 我在備註區塊輸入「不要百合花」
  • And 我點擊「新增備註」按鈕
  • Then 系統應儲存備註
  • And 新備註應立即顯示在備註列表最上方
  • And 備註應自動記錄當前時間與我的姓名

Scenario 10: 查看客戶地址列表​

  • Given 我在客戶「王小明」的詳情頁
  • And 該客戶有 2 個地址：
    1. 台北市信義區信義路五段 7 號（預設地址）
    2. 新北市板橋區中山路一段 100 號
  • Then 地址區塊應顯示所有地址
  • And 預設地址應有特殊標記（星號或徽章）
  • And 每個地址應可編輯/刪除

Scenario 11: 企業客戶詳情頁（額外資訊）​

  • Given 我在企業客戶「XX 科技公司」的詳情頁
  • Then 頁面應額外顯示企業客戶特有資訊：
    • 統一編號: 12345678
    • 產業類別: 科技
    • 合作開始日期: 2025-01-01
    • 月結帳期: 月結 30 天
  • And 聯絡人列表應顯示所有聯絡人
  • And 主要聯絡人應有特殊標記

Scenario 12: 無訂單歷史的新客戶​

  • Given 我在新客戶「李大華」的詳情頁
  • And 該客戶尚未下過任何訂單
  • Then 訂單歷史區塊應顯示「尚無訂單記錄」訊息
  • And 應顯示「為此客戶創建訂單」按鈕
  • And 消費統計區塊應顯示：
    • 總訂單數: 0 筆
    • 累計消費金額: $0
    • 平均訂單金額: N/A
  • And 消費趨勢圖表應顯示空狀態

業務規則 (Business Rules)​

  1. 訂單歷史顯示規則

    • 預設顯示最近 10 筆訂單
    • 包含所有狀態的訂單（已完成/進行中/已取消）
    • 依訂單日期降序排列

  2. 消費統計計算規則

    • 累計消費金額: 僅計算「已完成」且「已支付」的訂單
    • 總訂單數: 包含所有狀態的訂單（不含已取消）
    • 平均訂單金額: 累計消費金額 / 總訂單數（已完成的訂單）
    • 最常購買商品: 統計所有已完成訂單的商品項目

  3. 消費趨勢圖表規則

    • 統計近 12 個月的消費金額
    • 僅計算「已完成」且「已支付」的訂單
    • 月份無訂單時顯示 $0

  4. 客戶備註規則

    • 備註為內部使用（不顯示給客戶）
    • 每筆備註自動記錄時間與記錄人
    • 備註不可刪除（僅可新增）

  5. 地址管理規則

    • 客戶可有多個地址
    • 必須有一個預設地址（若僅一個地址，自動設為預設）
    • 刪除地址時若為預設地址，需先設定其他地址為預設

  6. 多租戶隔離

    • 訂單歷史僅顯示當前租戶的訂單
    • 客戶詳情頁需檢查客戶是否屬於當前租戶

UI/UX 需求 (UI/UX Requirements)​

頁面佈局​

桌面版​

┌─────────────────────────────────────────────────┐
│ 客戶詳情                    [編輯] [停用客戶]    │
├─────────────────────────────────────────────────┤
│ ┌─ 客戶資訊卡片 ────────────────────────────┐   │
│ │ ABC-CUST-000001          [VIP] [啟用]     │   │
│ │ 王小明                                     │   │
│ │ 0912-345-678 │ wang@example.com           │   │
│ │ 註冊: 2025-01-15 │ 最後消費: 2025-10-31   │   │
│ └───────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│ ┌─ 消費統計 ───────────────────────────────┐   │
│ │ 總訂單: 12 筆 │ 累計: $8,500 │ 平均: $708 │   │
│ │                                            │   │
│ │ 最常購買商品 (Top 3):                      │   │
│ │ 1. 玫瑰花束 (5 次, 42%)                    │   │
│ │ 2. 百合花束 (3 次, 25%)                    │   │
│ │ 3. 祝賀花籃 (2 次, 17%)                    │   │
│ │                                            │   │
│ │ [消費趨勢圖表 - 近 12 個月折線圖]          │   │
│ └───────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│ ┌─ 訂單歷史 (最近 10 筆) ───────────────────┐   │
│ │ 訂單編號        日期      金額    狀態     │   │
│ │ ABC-20251031-0001 10/31  $1,200  已完成   │   │
│ │ ABC-20251015-0005 10/15  $800    已完成   │   │
│ │ ...                                        │   │
│ │                    [查看所有訂單 →]        │   │
│ └───────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│ ┌─ 地址管理 ───────────────────────────────┐   │
│ │ ⭐ 台北市信義區信義路五段 7 號 (預設)      │   │
│ │    新北市板橋區中山路一段 100 號          │   │
│ │                          [新增地址]       │   │
│ └───────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│ ┌─ 客戶備註 ───────────────────────────────┐   │
│ │ 2025-10-01 10:00 - 店員 A                 │   │
│ │ 「喜歡粉色玫瑰」                           │   │
│ │                                            │   │
│ │ 2025-09-15 14:30 - 店員 B                 │   │
│ │ 「需提前一天確認配送時間」                 │   │
│ │                                            │   │
│ │ [新增備註.........................]  [送出]│   │
│ └───────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

手機版（卡片模式）​

┌─────────────────────┐
│ ← 客戶詳情    [•••] │
├─────────────────────┤
│ ┌─ 客戶資訊 ──────┐ │
│ │ ABC-001   [VIP] │ │
│ │ 王小明   [啟用] │ │
│ │ 0912-345-678    │ │
│ └─────────────────┘ │
├─────────────────────┤
│ ┌─ 消費統計 ──────┐ │
│ │ 訂單: 12 筆     │ │
│ │ 累計: $8,500    │ │
│ │ [圖表折疊]      │ │
│ └─────────────────┘ │
├─────────────────────┤
│ ┌─ 訂單歷史 ──────┐ │
│ │ ABC-20251031... │ │
│ │ 10/31 | $1,200  │ │
│ │ [查看所有 →]    │ │
│ └─────────────────┘ │
└─────────────────────┘

互動行為​

  1. 客戶資訊卡片

    • 顯示客戶等級徽章（VIP/VVIP）
    • 顯示客戶狀態徽章（啟用/停用）
    • 點擊「編輯」按鈕進入編輯模式
    • 點擊「停用客戶」按鈕開啟確認 Modal（僅管理者）

  2. 消費統計區塊

    • 使用 StatCard 組件顯示關鍵指標
    • 最常購買商品以進度條顯示佔比
    • 消費趨勢圖表使用 Recharts（折線圖）
    • Hover 時顯示該月詳細金額

  3. 訂單歷史列表

    • 點擊訂單編號進入訂單詳情頁
    • 訂單狀態以徽章顯示（已完成/進行中/已取消）
    • 「查看所有訂單」連結導航至訂單列表頁並套用過濾

  4. 地址管理

    • 預設地址以星號標記
    • 每個地址顯示編輯/刪除按鈕（Hover 時顯示）
    • 點擊「新增地址」按鈕開啟內嵌表單

  5. 客戶備註

    • 備註以時間線形式顯示
    • 新增備註時顯示文字輸入框
    • 按 Enter 或點擊「送出」按鈕提交

錯誤訊息​

  • API 錯誤: Toast 通知「載入失敗，請稍後再試」
  • 無訂單歷史: 「尚無訂單記錄」+ 「創建訂單」按鈕

載入狀態​

  • 頁面載入中: Skeleton 載入動畫（卡片區塊）
  • 圖表載入中: Spinner

技術規格 (Technical Specifications)​

API 端點​

1. 獲取客戶詳情​

  • 端點: GET /api/v1/customers/{id}
  • 權限要求: ROLE_STAFF 或更高
  • 多租戶隔離: 檢查客戶是否屬於當前租戶

響應 Payload:

{
  "id": "abc123",
  "customerNumber": "ABC-CUST-000001",
  "type": "individual", // 'individual' | 'corporate'
  "name": "王小明",
  "companyName": null,
  "phone": "0912345678",
  "email": "wang@example.com",
  "status": "active", // 'active' | 'inactive'
  "tier": "vip", // 'regular' | 'vip' | 'vvip'
  "tags": ["常客", "喜歡玫瑰"],
  "totalSpent": 8500,
  "totalOrders": 12,
  "averageOrderAmount": 708,
  "lastOrderDate": "2025-10-31T10:00:00Z",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-10-31T10:00:00Z",

  // 個人客戶專屬
  "gender": "male", // 'male' | 'female' | 'other'
  "birthday": "1990-05-15",

  // 企業客戶專屬
  "taxId": null,
  "industry": null,
  "cooperationStartDate": null,
  "paymentTerms": null,

  // 地址
  "addresses": [
    {
      "id": "addr1",
      "address": "台北市信義區信義路五段 7 號",
      "isDefault": true,
      "label": "住家"
    }
  ],

  // 聯絡人（企業客戶）
  "contacts": []
}

2. 獲取客戶訂單歷史​

  • 端點: GET /api/v1/customers/{id}/orders
  • 權限要求: ROLE_STAFF 或更高

查詢參數:

{
  limit?: number, // 預設: 10
  page?: number, // 預設: 1
}

響應 Payload:

{
  "orders": [
    {
      "id": "order1",
      "orderNumber": "ABC-20251031-0001",
      "orderDate": "2025-10-31T10:00:00Z",
      "totalAmount": 1200,
      "status": "completed", // 'pending' | 'in_progress' | 'completed' | 'cancelled'
      "deliveryDate": "2025-11-01"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalPages": 2,
    "totalItems": 12
  }
}

3. 獲取客戶消費統計​

  • 端點: GET /api/v1/customers/{id}/stats
  • 權限要求: ROLE_STAFF 或更高

響應 Payload:

{
  "totalOrders": 12,
  "totalSpent": 8500,
  "averageOrderAmount": 708,
  "lastOrderDate": "2025-10-31T10:00:00Z",

  // Top 3 最常購買商品
  "topProducts": [
    {
      "productId": "prod1",
      "productName": "玫瑰花束（12 朵）",
      "purchaseCount": 5,
      "percentage": 42 // 5 / 12 = 0.42
    },
    {
      "productId": "prod2",
      "productName": "百合花束（6 朵）",
      "purchaseCount": 3,
      "percentage": 25
    },
    {
      "productId": "prod3",
      "productName": "祝賀花籃",
      "purchaseCount": 2,
      "percentage": 17
    }
  ],

  // 近 12 個月消費趨勢
  "monthlyTrend": [
    { "month": "2024-11", "amount": 500 },
    { "month": "2024-12", "amount": 800 },
    { "month": "2025-01", "amount": 1200 },
    // ...
  ]
}

4. 獲取客戶備註​

  • 端點: GET /api/v1/customers/{id}/notes
  • 權限要求: ROLE_STAFF 或更高

響應 Payload:

{
  "notes": [
    {
      "id": "note1",
      "content": "喜歡粉色玫瑰",
      "createdAt": "2025-10-01T10:00:00Z",
      "createdBy": {
        "id": "user1",
        "name": "店員 A"
      }
    }
  ]
}

5. 新增客戶備註​

  • 端點: POST /api/v1/customers/{id}/notes
  • 權限要求: ROLE_STAFF 或更高

請求 Payload:

{
  "content": "不要百合花"
}

響應 Payload:

{
  "id": "note2",
  "content": "不要百合花",
  "createdAt": "2025-11-04T10:00:00Z",
  "createdBy": {
    "id": "user2",
    "name": "店員 B"
  }
}

元件架構​

src/applets/customer-applet/
├── CustomerDetailPage.tsx          # 客戶詳情主頁面
├── components/
│   ├── CustomerInfoCard.tsx        # 客戶資訊卡片
│   ├── CustomerStatsCard.tsx       # 消費統計卡片
│   ├── CustomerOrderHistory.tsx    # 訂單歷史列表
│   ├── CustomerTrendChart.tsx      # 消費趨勢圖表
│   ├── CustomerAddressList.tsx     # 地址列表
│   ├── CustomerNotes.tsx           # 客戶備註
│   └── TopProductsList.tsx         # 最常購買商品列表
├── hooks/
│   ├── useCustomerDetail.ts        # 客戶詳情邏輯
│   ├── useCustomerStats.ts         # 消費統計邏輯
│   └── useCustomerNotes.ts         # 備註邏輯
└── types.ts                        # TypeScript 類型定義

測試需求 (Test Requirements)​

單元測試​

  • 消費統計計算邏輯（平均訂單金額）
  • Top 3 商品計算邏輯
  • 月份趨勢數據處理邏輯

整合測試​

  • 客戶詳情 API 整合
  • 訂單歷史 API 整合
  • 消費統計 API 整合
  • 客戶備註 API 整合

E2E 測試​

  • Scenario 1: 查看客戶詳情頁
  • Scenario 2: 查看訂單歷史列表
  • Scenario 3: 查看所有訂單
  • Scenario 4: 點擊訂單進入詳情頁
  • Scenario 5: 查看消費統計
  • Scenario 6: 查看 Top 3 商品
  • Scenario 7: 查看消費趨勢圖表
  • Scenario 8: 查看客戶備註
  • Scenario 9: 新增客戶備註
  • Scenario 10: 查看地址列表
  • Scenario 11: 企業客戶詳情頁
  • Scenario 12: 無訂單歷史的新客戶

驗收檢查清單 (Acceptance Checklist)​

  • 客戶詳情頁正確顯示基本資訊
  • 訂單歷史列表正確顯示（最近 10 筆）
  • 「查看所有訂單」連結功能正常
  • 點擊訂單進入詳情頁
  • 消費統計指標正確計算
  • Top 3 商品列表正確顯示
  • 消費趨勢圖表正確顯示
  • 客戶備註列表正確顯示
  • 新增客戶備註功能正常
  • 地址列表正確顯示
  • 企業客戶詳情頁額外資訊正確顯示
  • 無訂單歷史的新客戶空狀態正確
  • 響應式設計正常（桌面/手機）
  • 載入狀態正確顯示
  • 錯誤處理正確

Story Points​

估算: 8 points

理由:

  • 需要整合多個 API（詳情、訂單歷史、統計、備註）
  • 包含複雜的統計計算（Top 3 商品、消費趨勢）
  • 需要圖表組件（Recharts 折線圖）
  • 需要處理個人客戶與企業客戶的差異
  • 包含地址管理、備註管理等多個子功能

相關文檔​

最後更新: 2025-11-04 撰寫者: Product Team