# Code128 條碼功能實作文件 ## 📋 功能概述 已成功為甜點店 ERP 系統的商品建檔管理模組實作完整的 Code128 條碼功能，包含自動生成商品編號、條碼生成、預覽、下載與列印功能。 --- ## 🗂️ 資料結構設計 ### Product 介面（已更新） ```typescript export interface Product { id: string; // 系統內部 ID product_code: string; // 商品編號（系統自動生成，格式：ICE000001） name: string; // 商品名稱 type: ProductType; // 類型（原物料/成品） category: string; // 分類 unit: ProductUnit; // 單位 barcode_value: string; // 條碼內容（預設等於商品編號） stockQuantity: number; // 庫存數量 createdAt: string; // 建立日期 } ``` ### 商品編號規則 - **格式**：`ICE` + 6位數字（例如：ICE000001、ICE000245） - **生成邏輯**：自動遞增，系統找出最大序號後 +1 - **唯一性**：每個商品編號保證唯一 - **用途**：作為條碼內容的預設值 --- ## 🎨 UI 設計與 Wireframe ### 商品對話框結構 ``` ┌─────────────────────────────────────────────────┐ │ 編輯商品 / 新增商品 │ ├─────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ 商品編號: ICE000001 │ │ ← 商品編號區（僅編輯時顯示） │ │ 系統自動生成，不可修改 │ │ │ └─────────────────────────────────────────┘ │ │ │ │ 商品名稱 * 類型 * │ │ [__________] [原物料 ▼] │ │ │ │ 分類 * 單位 * │ │ [__________] [公斤 ▼] │ │ │ │ 庫存數量 │ │ [__________] │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ 條碼資訊 │ │ ← 條碼區 │ │ │ │ │ │ 條碼內容 │ │ │ │ [ICE000001_________] [🔄 重新生成] │ │ │ │ 條碼內容預設等於商品編號... │ │ │ │ │ │ │ │ 條碼預覽 (Code128) │ │ │ │ ┌───────────────────────────────────┐ │ │ │ │ │ ║│││││││││││││││││││││││║ │ │ │ │ │ │ ICE000001 │ │ │ │ │ └───────────────────────────────────┘ │ │ │ │ │ │ │ │ [⬇️ 下載條碼圖片] [🖨️ 列印條碼標籤] │ │ │ └─────────────────────────────────────────┘ │ │ │ │ [取消] [儲存變更] │ └─────────────────────────────────────────────────┘ ``` ### 條碼區功能說明 1. **商品編號顯示**（僅編輯模式） - 藍色背景區塊 - 顯示格式化的商品編號 - 註明「系統自動生成，不可修改」 2. **條碼內容** - 顯示當前條碼值 - 唯讀輸入框，等寬字體顯示 - 「重新生成」按鈕：將條碼值恢復為商品編號 3. **條碼預覽** - 使用 Code128 格式 - 白色背景，虛線邊框 - 自動即時更新 - 新增模式提示「條碼將在儲存後顯示」 4. **操作按鈕** - 下載條碼圖片（PNG 格式） - 列印條碼標籤（包含商品資訊） --- ## 🔧 技術實作 ### 使用的套件 ```typescript import JsBarcode from "jsbarcode"; ``` ### 核心組件 #### 1. BarcodeDisplay 組件 ```typescript // /components/BarcodeDisplay.tsx // 功能：使用 JsBarcode 生成 Code128 條碼 // 參數：value, width, height, displayValue ``` #### 2. ProductDialog 組件更新 **主要新增功能：** - 商品編號顯示區域 - 條碼內容輸入框（唯讀） - 條碼預覽區域 - 重新生成按鈕 - 下載與列印功能 #### 3. ProductManagement 組件更新 **新增函數：** ```typescript generateProductCode(): string ``` - 自動生成下一個商品編號 - 確保唯一性 - 格式：ICE + 6位數字 --- ## 🔄 業務邏輯流程 ### 新增商品流程 ``` 1. 使用者點擊「新增商品」 ↓ 2. 填寫商品基本資料（名稱、類型、分類等） ↓ 3. 條碼區顯示「條碼將在儲存後顯示」 ↓ 4. 點擊「新增商品」 ↓ 5. 系統自動生成 product_code (例：ICE000007) ↓ 6. barcode_value 自動設為 product_code ↓ 7. 商品儲存完成，可再次編輯查看條碼 ``` ### 編輯商品流程 ``` 1. 使用者點擊「編輯」按鈕 ↓ 2. 對話框顯示商品編號（藍色區塊） ↓ 3. 條碼區顯示當前條碼值與 Code128 條碼圖 ↓ 4. 可選操作： - 重新生成條碼（恢復為商品編號） - 下載條碼圖片 - 列印條碼標籤 ↓ 5. 修改其他資料後儲存 ``` ### 重新生成條碼 ``` 1. 點擊「重新生成條碼」按鈕 ↓ 2. barcode_value 更新為 product_code ↓ 3. 條碼圖自動重新渲染 ↓ 4. 顯示成功提示訊息 ``` ### 下載條碼圖片 ``` 1. 點擊「下載條碼圖片」 ↓ 2. 從 Canvas 取得條碼圖片 ↓ 3. 轉換為 PNG 格式 ↓ 4. 觸發瀏覽器下載 ↓ 5. 檔名：barcode-ICE000001.png ``` ### 列印條碼標籤 ``` 1. 點擊「列印條碼標籤」 ↓ 2. 開啟新視窗 ↓ 3. 顯示條碼圖 + 商品資訊 - 商品名稱 - 商品編號 ↓ 4. 自動觸發列印對話框 ↓ 5. 列印完成後關閉視窗 ``` --- ## 🎯 使用情境範例 ### 情境 1：新增新商品「芒果刨冰」 1. 店員點擊「新增商品」 2. 輸入商品資料： - 名稱：芒果刨冰 - 類型：成品 - 分類：冰品 - 單位：個 3. 點擊「新增商品」儲存 4. 系統自動生成： - product_code: ICE000245 - barcode_value: ICE000245 5. 商品建立完成，可在倉庫撿貨與 POS 掃碼使用 ### 情境 2：商品編號需要恢復 1. 某次誤操作後，條碼內容被意外修改 2. 管理者進入「編輯商品」 3. 看到條碼值與商品編號不一致 4. 點擊「重新生成條碼」 5. 系統將 barcode_value 重置為 product_code 6. 條碼恢復正常，可重新列印標籤 ### 情境 3：列印商品標籤 1. 倉庫收到新的原物料「法國麵粉」 2. 管理者編輯該商品資料 3. 點擊「列印條碼標籤」 4. 列印對話框顯示條碼與商品資訊 5. 連接標籤機或一般印表機列印 6. 將標籤貼在商品包裝上 --- ## 🔐 權限與錯誤處理 ### 權限控管 1. **商品編號修改** - 目前設定：不可修改（唯讀） - 未來擴充：可設定管理員權限允許修改 2. **條碼重新生成** - 所有可編輯商品的使用者皆可使用 - 建議：可加入操作記錄追蹤 ### 錯誤處理 #### 1. 條碼生成失敗 ```typescript // BarcodeDisplay 組件已處理 try { JsBarcode(canvasRef.current, value, {...}); } catch (error) { console.error("Error generating barcode:", error); // 顯示友善錯誤訊息 } ``` **可能原因：** - 條碼內容包含無效字符 - Code128 不支援的特殊符號 **解決方案：** - 確保商品編號僅包含英數字 - 顯示錯誤提示給使用者 #### 2. 條碼重複檢查 **目前實作：** - 商品編號自動遞增，保證唯一性 - barcode_value 預設等於 product_code **未來建議：** ```typescript // 儲存前檢查條碼重複 const isDuplicate = products.some( p => p.barcode_value === formData.barcode_value && p.id !== product?.id ); if (isDuplicate) { toast.error("條碼內容重複，請重新生成"); return; } ``` #### 3. 下載/列印失敗 **處理方式：** - 檢查 Canvas 元素是否存在 - 瀏覽器權限檢查 - 顯示友善錯誤訊息 --- ## 📊 商品列表更新 ### 新增欄位 商品列表已更新，新增「商品編號」欄位： ``` | 商品編號 | 商品名稱 | 類型 | 分類 | 條碼 | 單位 | 庫存數量 | 操作 | |-----------|-------------|--------|---------|-----------|------|----------|------| | ICE000001 | 法國麵粉 | 原物料 | 烘焙材料 | ICE000001 | 公斤 | 150 | ✏️🗑️ | | ICE000002 | 草莓蛋糕 | 成品 | 蛋糕 | ICE000002 | 個 | - | ✏️🗑️ | ``` ### 搜尋功能更新 搜尋框已支援商品編號搜尋： - 商品名稱 - **商品編號（新增）** - 條碼內容 - 分類 --- ## 🚀 未來擴充建議 ### 1. 批次條碼列印 ```typescript // 選擇多個商品，一次列印所有條碼標籤 const handleBatchPrint = (selectedProducts: Product[]) => { // 生成包含多個條碼的列印頁面 // 適合一次收貨多種商品的情境 } ``` ### 2. 自訂條碼規則 ```typescript // 允許管理員自訂商品編號前綴 interface BarcodeSettings { prefix: string; // 例：ICE, CAKE, RAW digitLength: number; // 例：6 startNumber: number; // 例：1 } ``` ### 3. 條碼掃描驗證 ```typescript // 使用手機或掃碼槍掃描條碼 // 驗證條碼是否存在於系統中 const handleBarcodeScan = (scannedValue: string) => { const product = products.find(p => p.barcode_value === scannedValue); if (product) { // 顯示商品詳情 } else { // 提示條碼不存在 } } ``` ### 4. 條碼操作記錄 ```typescript interface BarcodeLog { productId: string; action: 'generated' | 'regenerated' | 'printed' | 'downloaded'; oldValue?: string; newValue: string; timestamp: string; userId: string; } ``` ### 5. QR Code 支援 ```typescript // 除了 Code128，也支援 QR Code // QR Code 可包含更多資訊（URL、JSON 等） import QRCode from "qrcode"; ``` --- ## 📝 測試檢查清單 - [x] 新增商品時自動生成商品編號 - [x] barcode_value 預設等於 product_code - [x] Code128 條碼正確生成並顯示 - [x] 重新生成條碼功能正常 - [x] 下載條碼圖片功能正常 - [x] 列印條碼標籤功能正常 - [x] 商品編號在編輯時唯讀顯示 - [x] 商品列表顯示商品編號 - [x] 搜尋支援商品編號 - [x] 條碼生成錯誤處理 - [x] UI 符合 Guidelines 設計規範 - [x] 響應式設計（桌面版） --- ## 🎨 設計規範遵循 根據 Guidelines.md： 1. **主要動作按鈕** - 「新增商品」：使用 `button-filled-primary` - 「儲存變更」：使用 `button-filled-primary` 2. **次要動作按鈕** - 「取消」：使用 `button-outlined-primary` - 「重新生成」：使用 `button-outlined-primary` - 「下載條碼圖片」：使用 `button-outlined-primary` - 「列印條碼標籤」：使用 `button-outlined-primary` 3. **對比度檢查** - 所有按鈕的背景色與文字色皆符合對比度要求 - 使用 CSS 變數確保一致性 --- ## 📚 相關檔案清單 ### 新增檔案 - `/components/BarcodeDisplay.tsx` - 條碼顯示組件 ### 修改檔案 - `/components/ProductManagement.tsx` - 新增商品編號生成邏輯 - `/components/ProductDialog.tsx` - 新增條碼區域與相關功能 - `/components/ProductTable.tsx` - 新增商品編號欄位 ### 參考檔案 - `/styles/globals.css` - 按鈕與樣式定義 - `/guidelines/Guidelines.md` - 設計規範 --- ## 💡 使用建議 1. **定期備份商品資料** - 商品編號與條碼資訊非常重要 - 建議定期匯出資料 2. **標籤管理** - 建議使用熱感應標籤紙 - 條碼尺寸適合一般掃碼槍讀取 3. **倉庫作業流程** - 收貨時列印標籤並貼在商品上 - 撿貨時掃描條碼確認商品 - POS 結帳時掃描條碼計價 4. **條碼品質** - 確保列印清晰 - 避免條碼損壞或污損 - 定期更換磨損的標籤 --- ## 🔧 故障排除 ### 問題 1：條碼無法顯示 **可能原因：** - JsBarcode 套件未正確載入 - 條碼內容包含無效字符 **解決方式：** - 檢查控制台錯誤訊息 - 確認條碼內容僅包含英數字 ### 問題 2：列印視窗空白 **可能原因：** - 瀏覽器阻擋彈出視窗 - Canvas 尚未完成渲染 **解決方式：** - 允許瀏覽器彈出視窗 - 確認條碼已正確顯示後再列印 ### 問題 3：商品編號重複 **可能原因：** - 多個使用者同時新增商品 - 資料同步問題 **解決方式：** - 使用資料庫自動遞增序號 - 實作樂觀鎖定機制 --- ## 📞 技術支援 如有任何問題或建議，請聯繫開發團隊。 最後更新：2025-11-28