跳至主要内容

Scenario 1: 快速新增個人客戶（僅必填欄位）

User Story: US-301: 客戶基本資料管理

Given: 系統初始狀態​

已登入用戶​

{
  "userId": "staff-001",
  "email": "staff@florist.com",
  "role": "SALES_STAFF",
  "tenantId": "ROLE_FLORIST-abc",
  "tenantName": "ABC 花店",
  "name": "王店員"
}

租戶設定​

{
  "tenantId": "ROLE_FLORIST-abc",
  "tenantCode": "ABC",
  "customerNumberPrefix": "ABC-CUST-",
  "currentCustomerNumber": 0
}

When: 執行操作​

API 請求​

POST /api/v1/customers
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "type": "individual",
  "name": "李大華",
  "phone": "0912-345-678"
}

Then: 預期結果​

1. HTTP 響應狀態碼​

201 Created

2. 響應 Payload​

{
  "id": "cust-001",
  "customerNumber": "ABC-CUST-000001",
  "type": "individual",
  "name": "李大華",
  "phone": "0912345678",
  "email": null,
  "status": "active",
  "tier": "regular",
  "totalSpent": 0,
  "totalOrders": 0,
  "lastOrderDate": null,
  "createdAt": "2025-11-04T10:00:00Z",
  "updatedAt": "2025-11-04T10:00:00Z"
}

3. 資料庫狀態變更​

customers 表新增記錄​

{
  "id": "cust-001",
  "tenantId": "ROLE_FLORIST-abc",
  "customerNumber": "ABC-CUST-000001",
  "type": "individual",
  "name": "李大華",
  "phone": "0912345678",
  "email": null,
  "gender": null,
  "birthday": null,
  "status": "active",
  "tier": "regular",
  "totalSpent": 0,
  "totalOrders": 0,
  "lastOrderDate": null,
  "createdAt": "2025-11-04T10:00:00Z",
  "updatedAt": "2025-11-04T10:00:00Z",
  "createdBy": "staff-001"
}

4. 業務規則驗證​

✅ 客戶編號自動生成​

  • 格式: {租戶代碼}-CUST-{流水號}
  • 實際: ABC-CUST-000001
  • 流水號從 000001 開始

✅ 電話格式標準化​

  • 輸入: 0912-345-678
  • 儲存: 0912345678（移除連字號）

✅ 初始狀態設定​

  • 客戶狀態: active（啟用）
  • 客戶等級: regular（普通客戶）
  • 累計消費: 0
  • 總訂單數: 0

✅ 多租戶隔離​

  • 客戶自動關聯到 tenantId: ROLE_FLORIST-abc

5. 審計日誌​

{
  "action": "CREATE_CUSTOMER",
  "tenantId": "ROLE_FLORIST-abc",
  "userId": "staff-001",
  "resourceType": "customer",
  "resourceId": "cust-001",
  "details": {
    "customerNumber": "ABC-CUST-000001",
    "name": "李大華",
    "phone": "0912345678"
  },
  "timestamp": "2025-11-04T10:00:00Z"
}

驗證重點​

  • 僅使用必填欄位即可成功創建客戶
  • 客戶編號自動生成且格式正確
  • 電話號碼自動標準化（移除連字號）
  • 初始狀態正確設定（啟用、普通客戶）
  • 多租戶隔離正確
  • 審計日誌正確記錄

相關場景​