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

## 頁面概述
單一倉庫為單位管理各商品的安全庫存量。初版使用 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 串接
- [ ] 批次設定功能
- [ ] 匯出安全庫存設定報表
- [ ] 歷史變更記錄
- [ ] 多倉庫切換功能