first commit
This commit is contained in:
245
source-code/ERP(A-b)-倉庫管理/src/docs/safety-stock-page-spec.md
Normal file
245
source-code/ERP(A-b)-倉庫管理/src/docs/safety-stock-page-spec.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 安全庫存設定頁面 - 功能規格文件
|
||||
|
||||
## 頁面概述
|
||||
單一倉庫為單位管理各商品的安全庫存量。初版使用 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 結構
|
||||
|
||||
```typescript
|
||||
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[]; // 商品列表
|
||||
}
|
||||
```
|
||||
|
||||
### 範例資料
|
||||
```typescript
|
||||
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
|
||||
- ✅ **對比度**：所有按鈕的背景色與文字色具備足夠對比度
|
||||
|
||||
### 使用者體驗原則
|
||||
1. **安全性**：刪除/取消操作需要二次確認
|
||||
2. **即時反饋**：操作成功後立即更新 UI 並顯示 toast
|
||||
3. **錯誤處理**：輸入驗證錯誤即時顯示於輸入框下方
|
||||
4. **一致性**：與系統其他頁面保持一致的操作邏輯
|
||||
|
||||
---
|
||||
|
||||
## 技術實作重點
|
||||
|
||||
### 元件組成
|
||||
- `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`：輸入驗證錯誤訊息
|
||||
|
||||
### 核心功能
|
||||
1. **搜尋**：依商品名稱、編號、條碼進行即時搜尋
|
||||
2. **篩選**：依狀態類型過濾商品列表
|
||||
3. **開啟設定彈窗**：點擊設定按鈕，帶入商品資料
|
||||
4. **輸入驗證**：正整數驗證、錯誤訊息顯示
|
||||
5. **儲存設定**：更新 mock data 並即時反映於列表
|
||||
6. **取消設定**：清空輸入框時顯示確認對話框
|
||||
7. **狀態計算**：依據邏輯計算並顯示對應的狀態 Badge
|
||||
|
||||
---
|
||||
|
||||
## 未來擴展方向
|
||||
- [ ] 實際 API 串接
|
||||
- [ ] 批次設定功能
|
||||
- [ ] 匯出安全庫存設定報表
|
||||
- [ ] 歷史變更記錄
|
||||
- [ ] 多倉庫切換功能
|
||||
Reference in New Issue
Block a user