US-105: 商品庫存管理

User Story

作為 花店管理者 我想要 能夠追蹤和調整商品庫存數量 以便 確保庫存準確性，避免缺貨或超賣情況

---

驗收標準 (Acceptance Criteria)

Scenario 1: 查看商品庫存狀態

• Given 我是已登入的管理者
• And 我在商品列表頁面
• When 頁面載入完成
• Then 每個商品應顯示庫存狀態標籤：
  • 綠色「正常」: 庫存 > 低庫存警戒值
  • 橘色「低庫存」: 0 < 庫存 <= 低庫存警戒值
  • 紅色「缺貨」: 庫存 = 0

Scenario 2: 手動調整庫存（增加）

• Given 我是已登入的管理者
• And 商品「玫瑰花束」目前庫存為 10
• When 我點擊該商品的「調整庫存」按鈕
• And 我選擇操作類型為「進貨」
• And 我輸入數量「20」
• And 我填寫備註「供應商補貨」
• And 我點擊「確認」按鈕
• Then 商品庫存應更新為 30
• And 系統應記錄庫存調整記錄（+20，進貨）
• And 我應看到成功通知

Scenario 3: 手動調整庫存（減少）

• Given 我是已登入的管理者
• And 商品「玫瑰花束」目前庫存為 30
• When 我點擊該商品的「調整庫存」按鈕
• And 我選擇操作類型為「報廢」
• And 我輸入數量「5」
• And 我填寫備註「花材枯萎報廢」
• And 我點擊「確認」按鈕
• Then 商品庫存應更新為 25
• And 系統應記錄庫存調整記錄（-5，報廢）

Scenario 4: 訂單自動扣減庫存

• Given 商品「玫瑰花束」目前庫存為 25
• When 有一筆訂單包含 2 個「玫瑰花束」
• And 訂單狀態從「待確認」變為「已確認」
• Then 商品庫存應自動扣減為 23
• And 系統應記錄庫存調整記錄（-2，訂單扣減，訂單編號：XXX）

Scenario 5: 訂單取消自動回補庫存

• Given 商品「玫瑰花束」目前庫存為 23
• And 有一筆已確認訂單包含 2 個「玫瑰花束」
• When 該訂單被取消
• Then 商品庫存應自動回補為 25
• And 系統應記錄庫存調整記錄（+2，訂單取消回補，訂單編號：XXX）

Scenario 6: 查看庫存調整歷史

• Given 我是已登入的管理者
• And 我在商品「玫瑰花束」的詳情頁
• When 我點擊「庫存記錄」標籤
• Then 我應看到該商品的所有庫存調整記錄
• And 每筆記錄應顯示：日期時間、調整類型、數量變化、調整後庫存、操作者、備註

Scenario 7: 低庫存警報通知

• Given 商品「玫瑰花束」的低庫存警戒值為 5
• And 目前庫存為 6
• When 有一筆訂單扣減庫存 2 個
• And 庫存變為 4（低於警戒值）
• Then 系統應發送低庫存警報通知給管理者
• And 商品列表中該商品應顯示「低庫存」警示標籤

Scenario 8: 庫存不足無法確認訂單

• Given 商品「玫瑰花束」目前庫存為 3
• And 有一筆訂單包含 5 個「玫瑰花束」
• When 嘗試將訂單狀態改為「已確認」
• Then 系統應顯示警告「商品『玫瑰花束』庫存不足（需要 5，僅剩 3）」
• And 系統應詢問「是否仍要確認訂單？」
• And 若確認，則允許超賣（庫存變為 -2）

Scenario 9: 設定低庫存警戒值

• Given 我是已登入的管理者
• And 我在商品「玫瑰花束」的編輯頁面
• When 我修改低庫存警戒值從 5 改為 10
• And 我點擊「儲存」按鈕
• Then 低庫存警戒值應更新為 10
• And 若目前庫存 <= 10，應觸發低庫存警報

Scenario 10: 批量調整庫存

• Given 我是已登入的管理者
• And 我在商品列表頁面
• When 我勾選多個商品
• And 我點擊「批量調整庫存」按鈕
• And 我選擇操作類型為「盤點調整」
• And 我為每個商品輸入實際庫存數量
• And 我點擊「確認」按鈕
• Then 所有選中商品的庫存應更新為輸入的數量
• And 系統應記錄每個商品的盤點調整記錄

Scenario 11: 庫存調整數量驗證（錯誤場景）

• Given 我是已登入的管理者
• And 我在調整商品庫存
• When 我輸入數量為「-10」
• Then 系統應顯示錯誤訊息「數量必須大於 0」
• When 我輸入數量為「abc」
• Then 系統應顯示錯誤訊息「請輸入有效的數字」

---

業務規則 (Business Rules)

1. 庫存調整類型

   類型	說明	庫存變化
   purchase	進貨	+
   return	退貨入庫	+
   order_cancel	訂單取消回補	+
   order	訂單扣減	-
   damage	報廢/損壞	-
   adjustment	盤點調整	+/-
   transfer	調撥（預留）	+/-

2. 庫存扣減時機

   • 訂單狀態從「待確認」→「已確認」時扣減
   • 不是在創建訂單時扣減（允許預約訂單）

3. 庫存回補時機

   • 訂單取消時自動回補
   • 僅回補「已確認」後被取消的訂單
   • 「待確認」狀態取消不需回補（未扣減過）

4. 超賣處理

   • 系統允許超賣（庫存可為負數）
   • 超賣時顯示警告但不阻止操作
   • 超賣記錄需標記以便追蹤

5. 低庫存警報規則

   • 庫存 <= 低庫存警戒值時觸發
   • 每個商品每天最多發送一次警報
   • 警報發送給 ROLE_MANAGER 以上角色

6. 庫存記錄保留

   • 所有庫存調整記錄永久保留
   • 記錄包含：時間、類型、數量、操作者、關聯訂單、備註

7. 權限規則

   • ROLE_STAFF: 僅可查看庫存
   • ROLE_MANAGER: 可調整庫存、設定警戒值
   • ROLE_OWNER: 可批量調整、查看完整歷史

8. 客製化專案庫存

   • 客製化專案（custom 類型）不追蹤庫存
   • 庫存相關欄位對客製化專案隱藏

---

UI/UX 需求 (UI/UX Requirements)

庫存調整 Modal

┌─────────────────────────────────────┐
│  調整庫存 - 玫瑰花束            [×] │
├─────────────────────────────────────┤
│  目前庫存: 25                       │
│                                     │
│  調整類型 *                         │
│  ┌─────────────────────────────┐   │
│  │ 進貨                    ▼   │   │
│  └─────────────────────────────┘   │
│                                     │
│  調整數量 *                         │
│  ┌─────────────────────────────┐   │
│  │ 20                          │   │
│  └─────────────────────────────┘   │
│                                     │
│  調整後庫存: 45                     │
│                                     │
│  備註                               │
│  ┌─────────────────────────────┐   │
│  │ 供應商補貨                  │   │
│  └─────────────────────────────┘   │
│                                     │
│           [取消]    [確認調整]      │
└─────────────────────────────────────┘

庫存調整歷史表格

日期時間	調整類型	變化	調整後	操作者	備註
12/03 14:30	訂單扣減	-2	23	系統	訂單 ABC-001
12/03 10:00	進貨	+20	25	張經理	供應商補貨
12/02 16:00	報廢	-5	5	王店長	花材枯萎

批量調整介面

批量庫存調整（盤點）

┌──────────────────────────────────────────────────┐
│ 商品名稱          目前庫存    實際庫存    差異   │
├──────────────────────────────────────────────────┤
│ 玫瑰花束（12朵）     25      [  23  ]     -2    │
│ 百合花束             18      [  20  ]     +2    │
│ 蝴蝶蘭盆花           10      [  10  ]      0    │
└──────────────────────────────────────────────────┘

盤點備註: [                                    ]

                              [取消]  [確認盤點]

---

技術規格 (Technical Specifications)

API 端點

1. 調整單一商品庫存

• 端點: POST /api/v1/products/{id}/inventory/adjust
• 權限: ROLE_MANAGER 或更高

請求 Payload:

{
  "type": "purchase", // 調整類型
  "quantity": 20,     // 調整數量（正數）
  "note": "供應商補貨"
}

2. 批量調整庫存

• 端點: POST /api/v1/products/inventory/batch-adjust
• 權限: ROLE_OWNER

請求 Payload:

{
  "type": "adjustment",
  "adjustments": [
    { "productId": "prod-001", "actualStock": 23 },
    { "productId": "prod-002", "actualStock": 20 }
  ],
  "note": "月度盤點"
}

3. 獲取庫存調整歷史

• 端點: GET /api/v1/products/{id}/inventory/history
• 權限: ROLE_STAFF 或更高

資料模型

interface InventoryAdjustment {
  id: string;
  tenantId: string;
  productId: string;
  type: InventoryAdjustmentType;
  quantityChange: number;    // 變化量（可為負）
  stockBefore: number;       // 調整前庫存
  stockAfter: number;        // 調整後庫存
  orderId?: string;          // 關聯訂單（若有）
  note?: string;             // 備註
  createdAt: Date;
  createdBy: string;         // 操作者 ID
}

type InventoryAdjustmentType =
  | 'purchase'      // 進貨
  | 'return'        // 退貨入庫
  | 'order_cancel'  // 訂單取消回補
  | 'order'         // 訂單扣減
  | 'damage'        // 報廢/損壞
  | 'adjustment';   // 盤點調整

---

Story Points

估算: 5 points

理由:

• 需要處理多種庫存調整類型
• 訂單相關的自動扣減/回補邏輯較複雜
• 批量調整功能增加複雜度
• 需要整合通知系統（低庫存警報）

---

相關文檔

• Epic 1: 產品與作品集管理
• US-101: 商品基本資料管理
• US-201: 創建訂單

---

最後更新: 2025-12-03 撰寫者: AI Assistant