FPSMS-backend/docs/user-guides/MTMS_BOM_使用說明.md

# MTMS 使用說明：BOM（匯入／啟停／應用）

> 本手冊依目前前端畫面與繁中文案整理，**按鈕／選單名稱以畫面上「」內文字為準**。  
> 適用範圍：側欄「設定」下的 BOM 相關頁、建立工單時選 BOM、排程「自動生成工單」。  
> **「一附」章節**使用本機資料庫 `fpsmsdb` 的真實例子（查詢當下快照）；其他環境請改條件再對。  
> 產生日期：依原始碼現況（若畫面改版，請以實際 UI 為準）。

---

## 這份手冊怎麼用

| 符號 | 意思 |
|------|------|
| 「……」 | 畫面上看得到的按鈕、選單、標題 |
| → | 下一步操作 |

建議閱讀順序：

1. **先匯入／啟用 BOM**（「設定」→「匯入 BOM」）  
2. **再檢查單位問題**（ADMIN：「BOM / 物料單位問題」）  
3. **再建工單／排程產單**（選 active BOM）  

---

## 一、整體流程（BOM 從主檔到工單）

```text
【匯入 BOM】Excel 上傳並檢查 →「確認匯入」
    ↓
【BOM 明細】確認「啟用」／必要時「停用」
    ↓（選做）「BOM 權重得分」調整加權
    ↓（ADMIN）「BOM / 物料單位問題」巡檢
    ↓
【建工單】「建立工單」選「BOM」
  或【排程】「自動生成工單」（僅含具 BOM 的物料）
```

---

## 一附、本地資料庫實例（方便對照畫面）

> 以下數字來自本機 `fpsmsdb` 查詢結果。**不同環境／日期資料會不同**。  
> BOM 狀態：`active`→「啟用」、`inactive`→「停用」。本機約有 **214** 筆啟用、**3** 筆停用。

### 例 A：啟用中的成品 BOM（適合在「BOM 明細」搜索）

| 「物品編號」 | 「物品名稱」 | 「BOM 狀態」 | 約材料筆數 |
|--------------|--------------|--------------|------------|
| PP2167 | 牛丼 | 啟用 | 10 |
| PP2277 | 烚意粉 | 啟用 | 3 |
| PP2390 | 熱情香果醬 | 啟用 | 4 |
| PP1224 | 柚子蒜蓉汁 | 啟用 | 5 |
| PP1136 | 白粥 | 啟用 | 9 |
| PP0259 | 牛肉水(2KG/包) | 啟用 | 0（無材料列，排程／提料前宜先確認） |

**怎麼練：**

1. 「設定」→「匯入 BOM」→ Tab「BOM 明細」。  
2. 「物品編號」填 **PP2167** →「搜索」。  
3. 載入後看「基本資訊」「材料清單」「製程與設備」；「BOM 狀態」應為「啟用」。

### 例 B：材料清單長什麼樣（PP2167 牛丼）

| 「物品編號」 | 「物品名稱」 | 約「基本數量」 |
|--------------|--------------|----------------|
| MA0471 | 日式超薄肥牛 | 272.16 |
| FA0164 | 洋蔥絲 | 145.15 |
| GI3236 | 清水 | 60.00 |
| PP2214 | 丼飯汁(2磅/包) | 41.73 |
| MG1507 | 江泉牌燒肉汁(1.8L/支) | 9.00 |
| MG1299 | 李錦記特選老抽(8L/桶) | 8.00 |
| MG0302 | 佛手牌味粉(10lb/罐) | 4.54 |
| MG0239 | 韓國雪白幼砂糖(30kg/包) | 4.54 |

### 例 C：用 BOM 建工單（接《排程與工單》手冊）

本機 **2026-07-29** 手動工單多掛在 active BOM 上，例如：

| 「工單編號」 | 「狀態」 | 成品 BOM | 「需求數量」 |
|--------------|----------|----------|--------------|
| JO-260729-038 | 待處理 | PP2277 烚意粉 | 51 |
| JO-260729-044 | 提料中 | PP2383 辣椒菜脯 | 265 |

**怎麼練：**「搜索工單/ 建立工單」→「建立工單」→「BOM」下拉選 **PP2277**（僅顯示啟用中的 BOM）。

### 自行查核用 SQL（選用）

```sql
SELECT b.code, i.name, b.status,
       (SELECT COUNT(*) FROM bom_material bm
        WHERE bm.bomId = b.id AND IFNULL(bm.deleted,0)=0) AS mats
FROM bom b
JOIN items i ON i.id = b.itemId
WHERE b.deleted = 0 AND b.code = 'PP2167';

SELECT i.code, i.name, bm.qty
FROM bom_material bm
JOIN items i ON i.id = bm.itemId
JOIN bom b ON b.id = bm.bomId
WHERE b.code = 'PP2167' AND IFNULL(bm.deleted,0)=0;
```

---

## 二、匯入 BOM（「設定」→「匯入 BOM」）

### 2.1 入口

- 側欄 **「設定」** → **「匯入 BOM」**（路徑通常為 `/settings/importBom`）  
- 頁內標題可能顯示英文 **Import BOM**；側欄與 Tab 以繁中「匯入 BOM」為準。

### 2.2 兩個分頁

| Tab | 用途 |
|-----|------|
| 「匯入 BOM」 | 上傳 Excel、檢查、確認寫入 |
| 「BOM 明細」 | 查已有 BOM、啟用／停用 |

### 2.3 操作步驟：上傳並匯入

1. 開 Tab **「匯入 BOM」**。  
2. **「選擇 BOM Excel 檔案」** →「選擇檔案」或「選擇資料夾」（可多選 `.xlsx`）。  
3. 確認「已選 N 個檔案」後，點 **「上傳並檢查」**。  
   - 進行中：「上傳與檢查中…」、進度「已檢查 x / y 個檔案…」。  
4. 檢視結果：  
   - 「正確 BOM 列表（可匯入）」  
   - 「問題 BOM 列表」  
5. 必要時勾選類型相關選項（如「飲料」「箱料粉」等）或用「搜索檔名」篩選。  
6. 確認無誤後點 **「確認匯入」**。  
7. 成功提示類似 **「匯入完成」**；亦可先「下載檢查結果 Excel」留底。  
8. 若要重來：點「返回重選檔案」。

### 2.4 常見錯誤（匯入）

| 畫面提示 | 建議處理 |
|----------|----------|
| 「請至少選擇一個 .xlsx 檔案」 | 先選檔再上傳 |
| 「上傳或檢查失敗，請稍後再試。」／伺服器 500 | 檢查網路／檔案格式後重試 |
| 檔名重複相關提示（_2、_3…） | 依提示整理檔名後重傳 |
| 「匯入失敗，請查看主控台。」 | 記下失敗檔，修正 Excel 後只重傳問題檔 |

---

## 三、BOM 明細：查詢與啟停

### 3.1 搜索

1. Tab **「BOM 明細」**。  
2. 「物品編號」／「物品名稱」→「搜索」／「重置」。  
3. 多筆時：「找到多筆 BOM，請選擇一筆載入明細」（按鈕上會標「成品｜半成品」「啟用｜停用」）。

### 3.2 可改什麼

| 區塊 | 說明 |
|------|------|
| 「BOM 狀態」 | 「啟用」／「停用」→「儲存狀態」 |
| 「基本資訊」 | 產出數量、類型、過敏原、色深／浮沉／濃淡、時段、複雜度、基礎得分等（多為檢視） |
| 「材料清單」 | 物品編號／名稱、基本／庫存／銷售數量與單位 |
| 「製程與設備」 | 製程檢視 |

> **注意：** 完整欄位線上「編輯／儲存」目前前端關閉（`SHOW_BOM_FULL_EDIT = false`）。日常維護以 **Excel 匯入** 與 **啟用／停用** 為主。

### 3.3 何時「停用」

- 配方作廢、暫不允許再建工單時，將「BOM 狀態」改「停用」並「儲存狀態」。  
- 「建立工單」的 BOM 下拉**只列出啟用**項目；停用後新單選不到該 BOM。

---

## 四、BOM 權重得分

### 4.1 入口

- 「設定」→ **「BOM 權重得分」**（`/settings/bomWeighting`）

### 4.2 分頁

| Tab | 用途 |
|-----|------|
| 「BOM 加權」 | 調整各評分項目的「權重」（總和須＝1） |
| 「BOM得分」 | 查看各貨品「基礎得分」 |

### 4.3 操作

1. 「BOM 加權」→「編輯」→改「權重」→「儲存」。  
2. 校驗失敗時：「權重必須為數字」或「權重總和必須等於 1（目前總和: x）」。  
3. 成功：「更新成功（已重新計算 N 筆 BOM 基礎分）」。  
4. 到「BOM得分」核對「貨品編號」「物品名稱」「基礎得分」。

---

## 五、BOM／物料單位問題（ADMIN）

### 5.1 入口

- 「設定」→ **「BOM / 物料單位問題」**（僅 **ADMIN**；`/settings/masterDataIssues`）  
- 頁標題常顯示：「BOM/貨品單位問題」

### 5.2 操作

1. Tab「BOM」或「貨品」。  
2. 「搜索」「類型」（「全部」「BOM 總表」「BOM 原材料」）。  
3. 「重新檢查」更新清單；「複製清單」方便貼到表單／郵件。  
4. 點列開詳情：「問題」「應為」「實際」→「關閉」。

### 5.3 常見問題文案（節錄）

- 「BOM 編號為空」「BOM 名稱為空」  
- 「BOM 產出單位與成品銷售單位不一致」  
- 「BOM 原料銷售／基本／庫存單位與貨品主檔不一致」  
- 「BOM 編號與關聯貨品不一致」  

側欄紅點例：`BOM N 筆 · 貨品 M 筆`。空狀態：「目前沒有問題。」

---

## 六、應用：建立工單時選 BOM

### 6.1 手動建立

1. 「管理工單」→「搜索工單/ 建立工單」→「建立工單」。  
2. **「BOM」**（必填）選成品／半成品；同名時可能標「（成品）」「（半成品）」。  
3. 「標準生產數」×「批數」＝「需求數量」（單位來自 BOM 產出 UOM）。  
4. 「預計生產日期」等填妥 →「建立」。  
5. 成功常提示「成功更新資料」。未選 BOM 時可能出現「請選擇 BOM」／`Bom required!`。

### 6.2 排程自動生成

1. 「排程」→「生產排程」→「詳細」。  
2. 「自動生成工單」（僅處理**具 BOM** 的物料；說明文案類似「選擇日期範圍（僅含具 BOM 的物料…）」）。  
3. 舊細排頁另有「生成工單」「查看 BOM」（材料表含「編號」「名稱」「可用數量」「需求數量」）。

詳見《MTMS 排程與工單 使用說明》。

---

## 七、權限與路徑速查

| 畫面 | 路徑 | 備註 |
|------|------|------|
| 匯入 BOM | `/settings/importBom` | 「設定」下 |
| BOM 權重得分 | `/settings/bomWeighting` | |
| BOM／物料單位問題 | `/settings/masterDataIssues` | **ADMIN** |
| 建立工單 | `/jo` | 選 active BOM |
| 排程產單 | `/ps` | 需 BOM |

---

## 八、常見問題速查

| 情況 | 建議 |
|------|------|
| 建工單下拉找不到某成品 | 到「BOM 明細」確認是否「啟用」；或尚未匯入 |
| 排程產單跳過某物料 | 該物料可能無 BOM／不在排期 BOM 範圍 |
| 單位對不上、品檢／提料異常 | ADMIN 開「BOM / 物料單位問題」對照主檔後修正 Excel 再匯入 |
| 權重儲存失敗 | 確認各權重為數字且總和＝1 |