跳至主要内容

Scenario 2: 新增企業客戶（含聯絡人資訊）

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": 1
}

When: 執行操作​

API 請求​

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

{
  "type": "corporate",
  "companyName": "XX 科技股份有限公司",
  "taxId": "12345678",
  "industry": "technology",
  "phone": "02-1234-5678",
  "address": "台北市信義區信義路五段 100 號",
  "email": "contact@xxtech.com",
  "contacts": [
    {
      "name": "張經理",
      "title": "業務經理",
      "phone": "0912-111-222",
      "email": "chang@xxtech.com",
      "isPrimary": true
    },
    {
      "name": "李助理",
      "title": "業務助理",
      "phone": "0912-333-444",
      "email": "lee@xxtech.com",
      "isPrimary": false
    }
  ],
  "cooperationStartDate": "2025-01-01",
  "paymentTerms": "net30"
}

Then: 預期結果​

1. HTTP 響應狀態碼​

201 Created

2. 響應 Payload​

{
  "id": "cust-002",
  "customerNumber": "ABC-CUST-000002",
  "type": "corporate",
  "companyName": "XX 科技股份有限公司",
  "taxId": "12345678",
  "industry": "technology",
  "phone": "0212345678",
  "address": "台北市信義區信義路五段 100 號",
  "email": "contact@xxtech.com",
  "status": "active",
  "tier": "regular",
  "totalSpent": 0,
  "totalOrders": 0,
  "lastOrderDate": null,
  "cooperationStartDate": "2025-01-01",
  "paymentTerms": "net30",
  "contacts": [
    {
      "id": "contact-001",
      "name": "張經理",
      "title": "業務經理",
      "phone": "0912111222",
      "email": "chang@xxtech.com",
      "isPrimary": true
    },
    {
      "id": "contact-002",
      "name": "李助理",
      "title": "業務助理",
      "phone": "0912333444",
      "email": "lee@xxtech.com",
      "isPrimary": false
    }
  ],
  "createdAt": "2025-11-04T10:05:00Z",
  "updatedAt": "2025-11-04T10:05:00Z"
}

3. 資料庫狀態變更​

customers 表新增記錄​

{
  "id": "cust-002",
  "tenantId": "ROLE_FLORIST-abc",
  "customerNumber": "ABC-CUST-000002",
  "type": "corporate",
  "companyName": "XX 科技股份有限公司",
  "taxId": "12345678",
  "industry": "technology",
  "phone": "0212345678",
  "address": "台北市信義區信義路五段 100 號",
  "email": "contact@xxtech.com",
  "status": "active",
  "tier": "regular",
  "totalSpent": 0,
  "totalOrders": 0,
  "lastOrderDate": null,
  "cooperationStartDate": "2025-01-01",
  "paymentTerms": "net30",
  "createdAt": "2025-11-04T10:05:00Z",
  "updatedAt": "2025-11-04T10:05:00Z",
  "createdBy": "staff-001"
}

customer_contacts 表新增記錄​

[
  {
    "id": "contact-001",
    "customerId": "cust-002",
    "name": "張經理",
    "title": "業務經理",
    "phone": "0912111222",
    "email": "chang@xxtech.com",
    "isPrimary": true,
    "createdAt": "2025-11-04T10:05:00Z"
  },
  {
    "id": "contact-002",
    "customerId": "cust-002",
    "name": "李助理",
    "title": "業務助理",
    "phone": "0912333444",
    "email": "lee@xxtech.com",
    "isPrimary": false,
    "createdAt": "2025-11-04T10:05:00Z"
  }
]

4. 業務規則驗證​

✅ 統一編號格式驗證​

  • 輸入: 12345678
  • 驗證: 8 位數字格式正確

✅ 聯絡人管理​

  • 至少一位聯絡人: ✅ (2 位)
  • 僅一位主要聯絡人: ✅ (張經理)

✅ 月結帳期設定​

  • 支付條款: net30（月結 30 天）

✅ 多租戶隔離​

  • 客戶與聯絡人都關聯到 tenantId: ROLE_FLORIST-abc

5. 審計日誌​

{
  "action": "CREATE_CUSTOMER",
  "tenantId": "ROLE_FLORIST-abc",
  "userId": "staff-001",
  "resourceType": "customer",
  "resourceId": "cust-002",
  "details": {
    "customerNumber": "ABC-CUST-000002",
    "companyName": "XX 科技股份有限公司",
    "taxId": "12345678",
    "contactsCount": 2
  },
  "timestamp": "2025-11-04T10:05:00Z"
}

驗證重點​

  • 企業客戶必填欄位驗證通過（公司名稱、電話、聯絡人）
  • 統一編號格式驗證正確（8 位數字）
  • 聯絡人資訊正確儲存（2 位聯絡人）
  • 主要聯絡人標記正確（僅一位）
  • 企業客戶專屬欄位正確儲存（產業類別、合作日期、月結帳期）
  • 多租戶隔離正確

相關場景​