US-107: 商品匯入/匯出
User Story
作為 花店管理者 我想要 能夠批量匯入和匯出商品資料 以便 快速建立商品目錄或備份商品資料
驗收標準 (Acceptance Criteria)
匯入功能
Scenario 1: 下載匯入範本
- Given 我是已登入的管理者
- And 我在「商品管理」頁面
- When 我點擊「匯入商品」按鈕
- And 我點擊「下載範本」連結
- Then 系統應下載 Excel 範本檔案（.xlsx）
- And 範本應包含所有欄位說明和範例資料
Scenario 2: 上傳商品檔案
- Given 我是已登入的管理者
- And 我在「匯入商品」頁面
- When 我上傳一個包含 20 筆商品的 Excel 檔案
- Then 系統應解析檔案並顯示預覽
- And 預覽應顯示每筆商品的資料
- And 系統應標示任何驗證錯誤
Scenario 3: 預覽並修正錯誤
- Given 我已上傳商品檔案
- And 預覽顯示第 5 筆資料有錯誤「價格格式錯誤」
- When 我在預覽介面修正第 5 筆的價格
- And 我點擊「重新驗證」
- Then 系統應重新驗證該筆資料
- And 若驗證通過，錯誤標記應消失
Scenario 4: 確認匯入商品
- Given 我已上傳商品檔案
- And 預覽顯示 20 筆資料全部驗證通過
- When 我點擊「確認匯入」按鈕
- Then 系統應批量創建 20 筆商品
- And 系統應自動生成每筆商品的 SKU 編號
- And 匯入完成後應顯示結果摘要
- And 摘要應包含：成功筆數、失敗筆數、失敗原因
Scenario 5: 匯入時處理重複商品
- Given 我已上傳商品檔案
- And 檔案中有一筆商品名稱與現有商品相同
- When 系統驗證檔案
- Then 該筆資料應標示為「警告：商品名稱已存在」
- And 系統應提供選項：
- 「略過」: 不匯入該筆
- 「創建新商品」: 以不同 SKU 創建
- 「更新現有商品」: 覆蓋現有資料
Scenario 6: 匯入檔案格式錯誤
- Given 我是已登入的管理者
- And 我上傳一個 PDF 檔案
- When 系統嘗試解析檔案
- Then 系統應顯示錯誤訊息「僅支援 .xlsx 或 .csv 格式」
Scenario 7: 匯入欄位對應設定
- Given 我上傳了一個自訂格式的 Excel 檔案
- And 欄位名稱與系統不同
- When 系統顯示欄位對應設定介面
- Then 我應可以手動對應每個欄位
- And 系統應嘗試自動對應相似欄位名稱
匯出功能
Scenario 8: 匯出全部商品
- Given 我是已登入的管理者
- And 系統中有 50 筆商品
- And 我在「商品管理」頁面
- When 我點擊「匯出商品」按鈕
- And 我選擇「全部商品」
- And 我選擇格式為「Excel (.xlsx)」
- Then 系統應生成並下載包含 50 筆商品的 Excel 檔案
Scenario 9: 匯出篩選後的商品
- Given 我是已登入的管理者
- And 我已篩選出類型為「花束」的商品（共 15 筆）
- When 我點擊「匯出商品」按鈕
- And 我選擇「目前篩選結果」
- Then 系統應生成並下載包含 15 筆商品的 Excel 檔案
Scenario 10: 選擇匯出欄位
- Given 我是已登入的管理者
- And 我在「匯出商品」設定頁面
- When 我取消勾選「成本價格」欄位
- And 我點擊「匯出」
- Then 匯出的檔案不應包含成本價格欄位
Scenario 11: 匯出為 CSV 格式
- Given 我是已登入的管理者
- When 我選擇匯出格式為「CSV (.csv)」
- And 我選擇編碼為「UTF-8 with BOM」
- Then 系統應生成 CSV 檔案
- And 檔案應可在 Excel 中正確顯示中文
業務規則 (Business Rules)
匯入規則
-
支援格式
- Excel (.xlsx) - 建議格式
- CSV (.csv) - 需指定編碼（UTF-8 或 Big5）
-
必填欄位
- 商品名稱
- 商品類型
- 基礎價格
-
選填欄位
- 商品描述
- 成本價格
- 庫存數量
- 低庫存警戒值
- 是否上架
- 是否熱門
- 是否新品
-
欄位驗證規則
欄位 驗證規則 商品名稱 1-100 字元，不可為空 商品類型 必須為有效的類型代碼 基礎價格 數字，> 0 成本價格 數字，>= 0 庫存數量 整數，>= 0 是否上架 是/否 或 true/false 或 1/0 -
批量限制
- 單次匯入最多 500 筆
- 檔案大小最大 5MB
-
重複處理
- 預設以商品名稱判斷重複
- 可選擇：略過、創建新商品、更新現有商品
-
照片匯入
- 目前版本不支援照片匯入
- 商品匯入後需手動上傳照片
匯出規則
-
支援格式
- Excel (.xlsx)
- CSV (.csv)
-
匯出範圍
- 全部商品
- 目前篩選結果
- 選取的商品
-
可選擇欄位
- 基本欄位（名稱、類型、價格等）- 預設勾選
- 成本價格 - 預設不勾選（敏感資訊）
- 庫存資訊 - 可選
- 時間戳記（創建/更新時間）- 可選
-
權限控制
ROLE_MANAGER以上可匯入/匯出- 成本價格欄位僅
ROLE_MANAGER以上可匯出
-
檔案命名
- 格式:
products_{租戶代碼}_{日期時間}.xlsx - 範例:
products_ABC_20251203_143000.xlsx
- 格式:
UI/UX 需求 (UI/UX Requirements)
匯入流程
Step 1: 上傳檔案
┌─────────────────────────────────────────────────┐
│ 匯入商品 [×] │
├─────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ │ │
│ │ 📄 拖曳檔案到此處上傳 │ │
│ │ 或 點擊選擇檔案 │ │
│ │ │ │
│ │ 支援 .xlsx, .csv (最大 5MB) │ │
│ │ │ │
│ └─────────────────────────────────────────┘ │
│ │
│ 📥 下載匯入範本 │
│ │
└─────────────────────────────────────────────────┘
Step 2: 欄位對應
┌─────────────────────────────────────────────────┐
│ 匯入商品 - 欄位對應 [×] │
├─────────────────────────────────────────────────┤
│ │
│ 檔案欄位 對應至系統欄位 │
│ ───────── ───────────── │
│ 品名 → [商品名稱 ▼] │
│ 種類 → [商品類型 ▼] │
│ 售價 → [基礎價格 ▼] │
│ 進價 → [成本價格 ▼] │
│ 數量 → [庫存數量 ▼] │
│ │
│ [上一步] [下一步] │
└─────────────────────────────────────────────────┘
Step 3: 預覽與驗證
┌─────────────────────────────────────────────────────────────┐
│ 匯入商品 - 預覽 [×] │
├─────────────────────────────────────────────────────────────┤
│ 共 20 筆 ✅ 18 筆正確 ❌ 2 筆錯誤 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ # │ 商品名稱 │ 類型 │ 價格 │ 狀態 │ │
│ ├───┼───────────────┼────────┼────────┼──────────────┤ │
│ │ 1 │ 玫瑰花束 │ 花束 │ 1200 │ ✅ 正確 │ │
│ │ 2 │ 百合盆花 │ 盆花 │ 800 │ ✅ 正確 │ │
│ │ 3 │ 測試商品 │ 花束 │ abc │ ❌ 價格錯誤 │ │
│ │ 4 │ │ 盆花 │ 500 │ ❌ 名稱必填 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 重複商品處理: [略過重複 ▼] │
│ │
│ [上一步] [確認匯入] │
└─────────────────────────────────────────────────────────────┘
Step 4: 匯入結果
┌─────────────────────────────────────────────────┐
│ 匯入完成 [×] │
├─────────────────────────────────────────────────┤
│ │
│ ✅ 匯入成功 │
│ │
│ 成功: 18 筆 │
│ 失敗: 2 筆 │
│ 略過: 0 筆 │
│ │
│ ⚠️ 2 筆資料因驗證錯誤未匯入 │
│ 📥 下載錯誤報告 │
│ │
│ [完成] │
└─────────────────────────────────────────────────┘
匯出介面
┌─────────────────────────────────────────────────┐
│ 匯出商品 [×] │
├─────────────────────────────────────────────────┤
│ │
│ 匯出範圍 │
│ ○ 全部商品 (50 筆) │
│ ● 目前篩選結果 (15 筆) │
│ ○ 選取的商品 (3 筆) │
│ │
│ 匯出格式 │
│ ● Excel (.xlsx) │
│ ○ CSV (.csv) │
│ │
│ 匯出欄位 │
│ ☑ 商品名稱 │
│ ☑ 商品類型 │
│ ☑ 基礎價格 │
│ ☐ 成本價格 │
│ ☑ 庫存數量 │
│ ☐ 創建時間 │
│ │
│ [取消] [匯出] │
└─────────────────────────────────────────────────┘
技術規格 (Technical Specifications)
API 端點
匯入相關
GET /api/v1/products/import/template- 下載匯入範本POST /api/v1/products/import/preview- 上傳並預覽POST /api/v1/products/import/execute- 確認匯入
匯出相關
POST /api/v1/products/export- 匯出商品
匯入預覽 API
端點: POST /api/v1/products/import/preview
請求: multipart/form-data with file
響應:
{
"totalRows": 20,
"validRows": 18,
"invalidRows": 2,
"rows": [
{
"rowNumber": 1,
"data": {
"name": "玫瑰花束",
"category": "bouquet",
"basePrice": 1200
},
"isValid": true,
"errors": []
},
{
"rowNumber": 3,
"data": {
"name": "測試商品",
"category": "bouquet",
"basePrice": "abc"
},
"isValid": false,
"errors": ["basePrice: 請輸入有效的數字"]
}
]
}
匯出 API
端點: POST /api/v1/products/export
請求:
{
"format": "xlsx", // "xlsx" | "csv"
"scope": "filtered", // "all" | "filtered" | "selected"
"productIds": [], // 若 scope 為 "selected"
"filters": { ... }, // 若 scope 為 "filtered"
"fields": ["name", "category", "basePrice", "stock"]
}
響應: Binary file download
Story Points
估算: 5 points
理由:
- 檔案解析與驗證邏輯較複雜
- 需要處理多種錯誤情況
- 欄位對應功能增加複雜度
- 匯出需要支援多種格式與欄位選擇
相關文檔
- Epic 1: 產品與作品集管理
- US-101: 商品基本資料管理
- US-306: 客戶匯入/匯出（參考，待創建）
最後更新: 2025-12-03 撰寫者: AI Assistant