mama/star-erp

Fork 0

Files

sky121113 c735c36009 first commit

2025-12-30 15:03:19 +08:00

7.2 KiB

Raw Blame History

安全庫存設定頁面 - 功能規格文件

頁面概述

單一倉庫為單位管理各商品的安全庫存量。初版使用 mock data 呈現，不涉及實際 API 串接。

頁面定位

路徑：/safety-stock
標題：[倉庫名稱] – 安全庫存設定（例如：A 倉庫 – 安全庫存設定）
僅顯示該倉庫中「曾有庫存紀錄的商品」

頁面架構

1. 頂部區塊

1.1 標題與說明

倉庫名稱：顯眼標題（h1）
說明文字：「僅顯示本倉庫曾有庫存紀錄的商品。安全庫存用於判斷庫存不足與缺貨提醒。」

1.2 搜尋欄位

輸入框：可搜尋商品名稱、商品編號或條碼
圖標：搜尋圖標（Search icon）
Placeholder：「搜尋商品名稱、商品編號或條碼」

1.3 篩選條件

下拉選單，包含以下選項：

全部商品：顯示所有商品（預設）
已設定安全庫存：只顯示 safetyStock !== null 的商品
有異常狀態：只顯示「低於安全庫存」或「缺貨」狀態的商品

2. 列表區塊

2.1 表格欄位

欄位名稱	說明	資料型態	顯示範例
商品名稱	商品的名稱	文字	高筋麵粉
商品編號	商品的編號	文字	P001
目前庫存	此倉庫的庫存數量 + 單位	數字 + 單位	150 kg
安全庫存量	設定的安全庫存數量	數字 + 單位或 "—"	50 kg / —
狀態	依據規則計算的狀態	Badge	正常 / 低於安全庫存 / 缺貨 / 未設定
操作	操作按鈕	按鈕	設定（outline button）

2.2 狀態計算規則

未設定：safetyStock === null
正常：safetyStock !== null && currentStock >= safetyStock
低於安全庫存：safetyStock !== null && currentStock > 0 && currentStock < safetyStock
缺貨：currentStock === 0 && safetyStock !== null

2.3 狀態顏色

未設定：灰色 Border Badge
正常：綠色 Border Badge
低於安全庫存：琥珀色 Border Badge
缺貨：紅色 Border Badge

2.4 特性

表格中的欄位全部為唯讀狀態
不提供 inline 編輯功能
所有修改必須透過「設定」按鈕開啟彈窗完成

3. 安全庫存設定彈窗（Modal）

3.1 觸發方式

使用者點擊表格某一列的「設定」按鈕

3.2 彈窗標題

設定安全庫存 – [商品名稱]（[倉庫名稱]）

範例：設定安全庫存 – 高筋麵粉（A 倉庫）

3.3 彈窗欄位

唯讀欄位（顯示用）

商品名稱
商品編號
倉庫名稱
目前庫存（含單位）

可編輯欄位

安全庫存量（數字輸入框）
- 類型：正整數
- 驗證：不得為負數或非數字
- 預設值：若已設定過安全庫存，帶入原數值
- 清空代表取消安全庫存設定

3.4 輔助文字

「當本倉庫庫存量低於安全庫存時，系統會顯示庫存不足提醒。」

3.5 按鈕

取消（outline button）：關閉彈窗，不儲存變更
儲存設定（filled button）：套用新的安全庫存數值

驗證與提示

4.1 輸入驗證

安全庫存量不得為負數
安全庫存量不得為非數字
必須為整數
若不合法，顯示錯誤訊息於輸入框下方

4.2 取消設定確認

當使用者清空安全庫存量欄位並按下儲存時：

顯示確認提示（AlertDialog）
標題：「確認取消安全庫存設定」
內容：「是否確認取消此商品在本倉庫的安全庫存設定？」
按鈕：
- 取消（outline）
- 確認取消設定（filled）

4.3 成功提示

儲存成功後關閉彈窗
顯示 toast 訊息
列表中該商品的「安全庫存量」與「狀態」即時更新

Mock Data 結構

interface SafetyStockItem {
  productId: string;        // 商品 ID
  productCode: string;      // 商品編號
  productName: string;      // 商品名稱
  productBarcode: string;   // 商品條碼
  unit: string;            // 單位（kg, L, 顆, mL 等）
  currentStock: number;     // 目前庫存
  safetyStock: number | null; // 安全庫存量（null 表示未設定）
}

interface SafetyStockSetting {
  warehouseId: string;      // 倉庫 ID
  warehouseName: string;    // 倉庫名稱
  items: SafetyStockItem[]; // 商品列表
}

範例資料

const MOCK_ITEMS: SafetyStockItem[] = [
  {
    productId: "prod-001",
    productCode: "P001",
    productName: "高筋麵粉",
    productBarcode: "4710001234567",
    unit: "kg",
    currentStock: 150,
    safetyStock: 50,  // 狀態：正常
  },
  {
    productId: "prod-002",
    productCode: "P002",
    productName: "細砂糖",
    productBarcode: "4710001234568",
    unit: "kg",
    currentStock: 30,
    safetyStock: 50,  // 狀態：低於安全庫存
  },
  {
    productId: "prod-003",
    productCode: "P003",
    productName: "無鹽奶油",
    productBarcode: "4710001234569",
    unit: "kg",
    currentStock: 0,
    safetyStock: 20,  // 狀態：缺貨
  },
  {
    productId: "prod-004",
    productCode: "P004",
    productName: "動物鮮奶油",
    productBarcode: "4710001234570",
    unit: "L",
    currentStock: 45,
    safetyStock: null,  // 狀態：未設定
  },
];

設計規範遵循

Guidelines 遵循

✅ 主要按鈕（儲存設定、確認取消設定）：使用 filled button class
✅ 次要按鈕（取消、設定、返回）：使用 outlined button class
✅ 輸入欄位：使用 Outlined style 的 border/outline
✅ 對比度：所有按鈕的背景色與文字色具備足夠對比度

使用者體驗原則

安全性：刪除/取消操作需要二次確認
即時反饋：操作成功後立即更新 UI 並顯示 toast
錯誤處理：輸入驗證錯誤即時顯示於輸入框下方
一致性：與系統其他頁面保持一致的操作邏輯

技術實作重點

元件組成

SafetyStockPage.tsx：主頁面元件
使用的 UI 元件：
- Button（filled / outline variants）
- Input（outlined style）
- Select（下拉篩選）
- Dialog（設定彈窗）
- AlertDialog（確認對話框）
- Badge（狀態標籤）
- Label（表單標籤）

狀態管理

items：商品列表資料
searchQuery：搜尋關鍵字
filterType：篩選類型（all / withSafety / abnormal）
selectedItem：當前選中要設定的商品
isDialogOpen：彈窗開啟狀態
safetyStockValue：彈窗中的安全庫存輸入值
showClearConfirm：取消設定確認對話框狀態
error：輸入驗證錯誤訊息

核心功能

搜尋：依商品名稱、編號、條碼進行即時搜尋
篩選：依狀態類型過濾商品列表
開啟設定彈窗：點擊設定按鈕，帶入商品資料
輸入驗證：正整數驗證、錯誤訊息顯示
儲存設定：更新 mock data 並即時反映於列表
取消設定：清空輸入框時顯示確認對話框
狀態計算：依據邏輯計算並顯示對應的狀態 Badge

未來擴展方向

實際 API 串接
批次設定功能
匯出安全庫存設定報表
歷史變更記錄
多倉庫切換功能

7.2 KiB Raw Blame History Unescape Escape