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