FPSMS-backend/docs/user-guides/MTMS_排程與工單_使用說明.md

# MTMS 使用說明：排程 → 開工單

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

---

## 這份手冊怎麼用

| 符號 | 意思 |
|------|------|
| 「……」 | 畫面上看得到的按鈕、選單、標題 |
| → | 下一步操作 |
| 節點 | 流程中的一個階段（狀態／畫面） |

建議閱讀順序：

1. **先排期**（側欄「排程」）  
2. **再放單／建工單**（「管理工單」→「搜索工單/ 建立工單」）  
3. **提料 → 生產 → 完成**  

---

## 一、整體流程（從排期到完工）

```text
【排程】預測／查看排期
    ↓ 「自動生成工單」  或  手動「建立工單」
【規劃中】工單已建立、尚未放單
    ↓ 「放單」
【待提料／提料中】
    ↓ 「工單提料」掃碼提交
【生產中】「工單生產流程」各工序開始／完成
    ↓ 「完成工單」
【品檢／上架】「待QC上架工單」→「已上架工單」
```

也可**不經排程**，在「搜索工單/ 建立工單」直接「建立工單」（手動工單）。

---

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

> 以下數字來自本機 `fpsmsdb` 查詢結果，用於說明「畫面上大概會看到什麼」。  
> **不同環境／日期資料會不同**；請用「搜索」條件改成你們當天日期再核對。  
> 狀態中文依前端翻譯：`planning`→「規劃中」、`pending`→「待處理」、`packaging`→「提料中」、`processing`→「生產中」、`storing`→「待品檢入倉」、`completed`→「已完成」。

### 例 A：已有排期、尚未產工單（適合練習「詳細」→「自動生成工單」）

在「生產排程」用「生產日期」搜 **2026-08-03**，本機有一筆細排（`production_schedule.id = 928`，`type = detailed`）：

| 畫面概念 | 本機資料 |
|----------|----------|
| 「生產日期」 | 2026-08-03 |
| 「預計生產數」（約） | 17,334 |
| 「成品款數」（約） | 47 |

打開「詳細」後，明細列會類似（節錄）：

| 「編號」 | 「名稱」 | 約「需求數量」 | 約「存貨量」 | 約需工單數 |
|----------|----------|----------------|--------------|------------|
| PP1175 | 鮮檸檬汁(P+4) | 1,406 | 1,400 | 74 |
| PP1224 | 柚子蒜蓉汁 | 140 | 50 | 1 |
| PP0259 | 牛肉水(2KG/包) | 41 | 51 | 41 |
| PP2284 | 油醋汁(1KG/包) | 28 | 32 | 1 |
| PP2390 | 熱情香果醬 | 12 | 16 | 4 |

**怎麼練：**

1. 「排程」→ 生產日期選 **2026-08-03** →「搜索」→「詳細」。  
2. 對照上表成品是否出現在明細。  
3. 若環境允許，再試「自動生成工單」（會真正建 JO，請在測試庫操作）。  

> 查詢當下：此排期**尚未**有透過 `prodScheduleLineId` 掛上的工單（適合示範「產工單前」）。

### 例 B：排期已產工單且已完成（歷史成功路徑）

本機較早一筆：**2026-06-17** 細排（約預計生產 17,421、成品款數 33），曾產生多張 `type = detailed` 工單，例如：

| 「工單編號」 | 「狀態」 | 「需求數量」 | 成品 |
|--------------|----------|--------------|------|
| JO-260617-008 | 已完成 | 568 | PP1234 日式咖哩汁 |
| JO-260617-012 | 已完成 | 15 | PP2288 香水檸檬汁P+3 |
| JO-260617-015 | 已完成 | 600 | PP1136 白粥 |
| JO-260617-024 | 已完成 | 28 | PP2284 油醋汁(1KG/包) |
| JO-260617-030 | 已完成 | 508 | PP2290 韓式豬軟骨 |

**怎麼練：**

1. 「搜索工單/ 建立工單」→「預計生產日期」填 **2026-06-17** →「搜索」。  
2. 找上表工單編號，點「查看」看已完成工單長怎樣。  
3. 對照：這類工單來自排程 release（`type` 在庫為 `detailed`），不是手動「建立工單」的 `manual`。

### 例 C：手動「建立工單」（不經排程）

本機 **2026-07-29** 工單幾乎皆為手動（`type = manual`，且未掛排期行）。例子：

| 「工單編號」 | 「狀態」 | 「需求數量」 | 成品 |
|--------------|----------|--------------|------|
| JO-260729-045 | 待處理 | 3 | PP2390 熱情香果醬 |
| JO-260729-038 | 待處理 | 51 | PP2277 烚意粉 |
| JO-260729-034 | 生產中 | 1 | PP2302 酸甜蘿蔔粒箱料粉 |
| JO-260729-044 | 提料中 | 265 | PP2383 辣椒菜脯 |

**怎麼練：**

1. 「預計生產日期」選 **2026-07-29** →「搜索」。  
2. 用「狀態」篩「待處理」→ 應能看到類似 JO-260729-045。  
3. 若該單仍「規劃中」，可練習「放單」；若已是「待處理」，可接「工單提料」。

同日狀態分佈（本機快照）：約 17 張「待處理」、24 張「提料中」、4 張「生產中」——正好對應「放單後 → 提料 → 生產」不同節點。

### 例 D：近兩週工單狀態分佈（看流程卡在哪）

本機最近約 14 天（未隱藏工單）概況：

| 「狀態」 | 約筆數 | 使用者下一步常做什麼 |
|----------|--------|----------------------|
| 已完成 | 359 | 可當完成範本「查看」 |
| 待處理 | 42 | 「工單提料」 |
| 提料中 | 37 | 繼續掃碼／提交提料 |
| 待品檢入倉 | 33 | 「工單生產流程」品檢／上架 |
| 生產中 | 4 | 「工單生產流程」繼續工序 |

### 例 E：還在「規劃中」的單（適合練刪除／放單）

本機仍有例如：**JO-260427-039**（沙薑醬 PP2205，需求約 291，「規劃中」）。

- 若只需練習「查看」→ 看「放單」「刪除工單」按鈕是否出現。  
- **勿在正式／共用庫隨意刪除**；測試庫才建議真的按「刪除工單」。

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

```sql
-- 某日排期摘要
SELECT id, DATE(produceAt) AS produce_date, type,
       totalEstProdCount, totalFGType
FROM production_schedule
WHERE deleted = 0 AND DATE(produceAt) = '2026-08-03';

-- 該排期成品明細（前 20）
SELECT i.code, i.name, psl.prodQty, psl.stockQty, psl.needNoOfJobOrder
FROM production_schedule_line psl
JOIN production_schedule ps ON ps.id = psl.prodScheduleId
JOIN items i ON i.id = psl.itemId
WHERE ps.deleted = 0 AND psl.deleted = 0
  AND DATE(ps.produceAt) = '2026-08-03'
ORDER BY psl.itemPriority, i.code
LIMIT 20;

-- 某日工單＋狀態
SELECT code, status, type, reqQty, DATE(planStart) AS plan_date
FROM job_order
WHERE deleted = 0 AND (isHidden = 0 OR isHidden IS NULL)
  AND DATE(planStart) = '2026-07-29'
ORDER BY status, code;
```

---

## 二、排程（側欄「排程」）

### 2.1 入口

- 側欄點 **「排程」**  
- 進入頁面標題：**「生產排程」**（路徑通常為 `/ps`）

> 說明：系統另有舊版「需求預測」「詳細排程」頁（`/scheduling/...`），**目前側欄主入口是「排程」→「生產排程」**。以下以主入口為準。

### 2.2 畫面上常見按鈕

| 按鈕／功能 | 用途（白話） |
|------------|--------------|
| 「預測排期」 | 依日期／天數**計算產生**預計排期 |
| 「搜索」 | 依「生產日期」等條件查已有排期 |
| 「詳細」 | 打開該筆排期的明細 |
| 「自動生成工單」 | 依此排期**一次產生多張工單**（在詳情裡） |
| 「關閉」 | 關閉詳情視窗 |
| 「排期設定」 | 庫存／排期相關設定與匯入匯出 |
| 「匯出計劃/物料需求Excel」 | 匯出計劃與物料需求 |
| 「匯出送貨單數量」 | 匯出送貨單數量區間資料 |

列表常見欄位：「生產日期」「預計生產數」「成品款數」等。

### 2.3 操作步驟：做出排期（Happy path）

1. 進入 **「排程」** → **「生產排程」**。  
2. 點 **「預測排期」**。  
3. 在對話框 **「準備生成預計排期」** 中填：  
   - 「開始日期」  
   - 「排期日數」  
4. 點 **「計算預測排期」**。  
5. 成功時畫面會提示類似 **「成功計算排期!」**；失敗會提示計算錯誤或不明狀況。  
6. 選擇「生產日期」後點 **「搜索」**，在列表找到該日排期。  
7. 點該列 **「詳細」**，打開 **「排期詳細」**。  
8. 確認內容無誤後，點 **「自動生成工單」** → 系統依排期建立工單。  
9. 點 **「關閉」** 結束。

### 2.4 節點說明（排程）

| 節點 | 使用者在做什麼 | 下一個常見動作 |
|------|----------------|----------------|
| 尚未有排期 | 進「生產排程」但列表空／無當日資料 | 「預測排期」 |
| 已有排期列表 | 用「搜索」找日期 | 「詳細」 |
| 排期詳細已打開 | 檢查預計生產內容 | 「自動生成工單」 |
| 已生成工單 | 工單出現在「搜索工單/ 建立工單」 | 去「放單」 |

### 2.5 排程常見問題

| 情況 | 建議處理 |
|------|----------|
| 「計算預測排期」失敗 | 記下畫面錯誤訊息；檢查開始日期／天數；稍後再試或聯絡系統／IT |
| 「自動生成工單」失敗 | 畫面可能顯示失敗訊息；確認排期內容是否完整、BOM／物料是否齊全 |
| 找不到某日排期 | 確認「生產日期」與「搜索」條件；必要時再跑一次「預測排期」 |
| 想改數量再開工單 | 主入口 `/ps` 詳情偏「一次自動生成」；若需逐行改量／發佈，需使用舊版「詳細排程」編輯頁（見附錄） |

### 2.6 附錄：舊版「詳細排程」／「需求預測」（進階）

若單位仍使用直連網址：

| 畫面 | 標題（約） | 重點按鈕 |
|------|------------|----------|
| 需求預測列表 | 「需求預測」 | 「測試粗排」「搜索」「詳情」 |
| 需求預測詳情 | 「成品及物料需求預測詳情」 | 多為**檢視**（依成品／依物料、「查看 BOM」） |
| 詳細排程列表 | 「詳細排程」 | 「詳細排程」（產生）、「匯出排程」「詳情」 |
| FG 生產排程 | 「成品生產排程」／「FG 生產排程」 | 列「發佈」、改「需求數量」後儲存、**「生成工單」**、「返回」 |

注意（舊版細排詳情）：

- **「生成工單」** 常僅允許**生產日期為今天**；否則可能跳出英文提示（畫面未必有完整中文翻譯）。  
- 前端**沒有**「從某一筆需求預測一鍵跳到對應詳細排程」的按鈕；兩條線在畫面上是分開的。

設定選單另有 **「需求預測設定」**（成品排除日、星期等），屬主檔設定，不是每日排期操作。

---

## 三、工單：搜索／建立／放單

### 3.1 入口

側欄 **「管理工單」** → **「搜索工單/ 建立工單」**

頁面標題：**「搜索工單/建立工單」**

### 3.2 畫面上常見按鈕

| 按鈕 | 用途 |
|------|------|
| 「建立工單」 | 手動開一張新工單 |
| 「放單」／「放單 (N)」 | 將「規劃中」工單放出，進入後續提料 |
| 「重置」 | 清空搜尋條件 |
| 「查看」 | 開「工單詳情」 |
| 「取消工單」 | 取消後工單從列表隱藏（非規劃中等情況） |

搜尋條件常見：「工單編號」「成品/半成品名稱」「預計生產日期」～「預計生產日期至」「工單類型」「狀態」。

### 3.3 操作步驟：手動建立工單

1. 點 **「建立工單」**，打開標題為 **「建立工單」** 的視窗。  
2. 填寫：  
   - 「BOM」  
   - 「標準生產數」（通常唯讀）  
   - 「批數」  
   - 「需求數量」（常由標準×批數自動帶出）  
   - 「工單類型」（選 BOM 後可能自動對應）  
   - 「生產優先序」（常見預設約 50，範圍約 1–100）  
   - 「預計生產日期」  
   - 可勾選「記住為預設日期」  
3. 點 **「建立」**。  
4. 成功後通常提示資料已更新；新工單多為 **「規劃中」** 狀態。  
5. 在列表勾選／找到該工單，點 **「放單」**（或上方「放單 (N)」批量）。  

### 3.4 操作步驟：從排程來的工單

1. 在「生產排程」詳情已按 **「自動生成工單」**（或舊版「生成工單」）。  
2. 到 **「搜索工單/ 建立工單」**，用「預計生產日期」等搜尋。  
3. 確認工單後執行 **「放單」**。  

### 3.5 工單詳情（「查看」）

標題：**「工單詳情」**

常見分頁／區塊：

- 「工單信息」  
- 「BOM 材料」  
- 「工藝流程」／「工藝明細」  

常見動作：

| 按鈕 | 何時可用（概念） | 說明 |
|------|------------------|------|
| 「放單」 | 多為「規劃中」 | 放出工單 |
| 「刪除工單」 | 多為仍在「規劃中」 | 確認後**無法復原** |
| 「取消工單」 | 已非規劃中等 | 確認後從列表**隱藏**；已上架通常不可取消 |
| 「儲存」／「取消」 | 編輯 Dialog | 存檔或放棄 |
| 「返回列表」 | — | 回搜尋頁 |

庫存摘要常見字樣：「所需貨品項目數量：」「可提料項目數量：」「未能提料項目數量：」。

刪除確認：

- 「確認刪除工單」  
- 「確定要刪除此工單嗎？此操作無法復原。」  

取消確認：

- 「確認取消工單」  
- 「確定要取消此工單嗎？工單將從列表中隱藏。」  
- 按鈕：「取消工單」／「取消」（後者為放棄這次取消操作）

### 3.6 工單狀態（搜尋／列表常見）

畫面上可能出現（實際以該列顯示為準）：

| 狀態（常見中文） | 白話 |
|------------------|------|
| 「規劃中」 | 已建立，尚未放單 |
| 「待處理」／待提料相關 | 已放單，等提料 |
| 「提料中」／「進行中」 | 正在提料或進行中 |
| 「已開始工序」／「生產中」 | 已進入生產工序 |
| 「成品入倉中」／「待品檢入倉」 | 生產後待品檢／入倉 |
| 「已上架」 | 已完成上架 |
| 「已取消」 | 已取消 |

篩選下拉亦可能見：「待處理」「提料中」「已開始工序」「成品入倉中」「已上架」「已取消」等。

### 3.7 工單建立／放單常見問題

| 情況 | 建議處理 |
|------|----------|
| 「建立」沒反應 | 檢查 BOM、批數、日期、工單類型是否已填；看是否有必填未選 |
| 「放單」失敗 | 記下提示；檢查是否仍為可放單狀態、物料／權限 |
| 想刪掉剛建錯的單 | 「規劃中」→「查看」→「刪除工單」→ 確認 |
| 已放單但不想做了 | 「取消工單」→ 確認隱藏；**已上架**通常不能取消 |
| 批量「放單 (N)」部分失敗 | 依成功／失敗筆數訊息，對失敗單再個別處理 |

---

## 四、工單提料

### 4.1 入口

**「管理工單」** → **「工單提料」**

### 4.2 常見分頁

- 「工單提料詳情」  
- 「已完成工單記錄」  
- 「物料提料狀態」  
- （及其他與膠茜／用量相關分頁，以畫面為準）

### 4.3 操作步驟（概念）

1. 在「工單提料詳情」找到已放單、待提料的工單。  
2. 點 **「查看詳情」** 進入提料執行畫面。  
3. 依畫面使用 **「開始掃碼」**、掃描物料／批號。  
4. 需要時點 **「提交」**／**「提交所有已掃描項目」**／**「確認」**。  
5. 完成後可在「已完成工單記錄」核對。  

對料相關：生產流程中可能有 **「工單對料」**，並有 **「確認所有提料」**。

### 4.4 提料常見問題

| 情況 | 建議處理 |
|------|----------|
| 批號不符 | 依 Dialog 提示按「確認」，改掃正確批號 |
| 庫存不足／過期 | 依畫面提示；先補貨或調批號，勿強行提交 |
| 掃錯要重來 | 用畫面上的「取消」／清除已掃項目（以當頁按鈕為準）後重掃 |

提料狀態常見：「待提料」「已掃碼」「對料待處理」「對料已完成」；提料單「已放單」「已完成」。

---

## 五、工單生產流程

### 5.1 入口

**「管理工單」** → **「工單生產流程」**

### 5.2 常見分頁／區塊

- 「工藝流程」  
- 「待QC上架工單」  
- 「已上架工單」  
- 「儀表板 - 工單狀態」等  

### 5.3 工序操作（Happy path）

1. 在「工藝流程」找到工單，點 **「查看詳情」**。  
2. （可選）**「工單對料」** 確認物料。  
3. 各工序：  
   - **「開始」** 開工序  
   - 可依畫面掃 **操作員**／**設備**（未掃可能提示「請先掃描操作員編號」「請掃描設備編號」）  
   - 可 **「暫停」**  
   - **「完成步驟」**／**「通過」**／**「已完成」**（Just Pass 等，以畫面為準）  
   - 確認通過時可能問：**「確認要通過此工序嗎？」**  
4. 全部就緒後點 **「完成工單」**，確認：**「確認要完成此工單嗎？」**  
5. 需要時做 **「品檢」**，再到「待QC上架工單」完成上架，最後在「已上架工單」可見。  

其他可能按鈕：「提交並開始」「提交包裝袋消耗」等。

### 5.4 工序狀態（常見）

「待處理」「進行中」「已暫停」「完成」／「已完成」「通過」「未開始」「已停止」「已取消」等。

### 5.5 生產常見問題

| 情況 | 建議處理 |
|------|----------|
| 「完成工單」按不了 | 通常尚有工序未完成或條件未滿足；先完成各步驟 |
| 掃碼驗證失敗 | 「驗證失敗. 請檢查操作員和設備.」→ 重掃正確編號 |
| API／系統錯誤 | 「發生錯誤，請稍後再試。」→ 稍後重試或聯絡支援 |
| 做到一半要停 | 用「暫停」；勿與「取消工單」混淆（取消是整張工單層級） |

---

## 六、取消、刪除、返回——怎麼選？

| 你想做的事 | 建議用哪個按鈕 | 結果 |
|------------|----------------|------|
| 建錯、還在規劃中，不要了 | 「刪除工單」 | 刪除，**不可復原** |
| 已放單／進行中，不要繼續 | 「取消工單」 | 確認後從列表**隱藏** |
| 只是關掉視窗、不改資料 | 「關閉」／「取消」／「返回」「返回列表」 | 不取消工單本身 |
| 工序暫停一下 | 「暫停」 | 工單仍在，之後可再「開始」 |

---

## 七、快速檢查清單（每日）

1. 「排程」→ 需要時「預測排期」→「搜索」→「詳細」→「自動生成工單」  
2. 「搜索工單/ 建立工單」→ 核對當日工單 →「放單」  
3. 「工單提料」→ 掃碼提交  
4. 「工單生產流程」→ 各工序開始／完成 →「完成工單」→ 品檢／上架  

手動補單：同頁「建立工單」→「建立」→「放單」。

---

## 八、文件維護說明（給內部）

- 文案來源：前端 `i18n/zh/navigation.json`、`jo.json`、`schedule.json`、`productionProcess.json`，以及「生產排程」頁硬編碼繁中。  
- 主程式入口：  
  - 排程：`FPSMS-frontend/src/app/(main)/ps/page.tsx`  
  - 工單搜尋／建立：`.../jo/page.tsx`、`JoWorkbenchSearch`、`JoCreateFormModal`  
  - 提料：`.../jodetail/`  
  - 生產：`.../productionProcess/`  
- 若按鈕改名或流程改版，請同步改本手冊，並重新匯出 Word。

重新匯出 Word（需已安裝套件）：

```bash
pip install python-docx
python scripts/export_user_guide_office.py
```

產出：`docs/exports/MTMS_Schedule_JobOrder_UserGuide.docx`