重構 Order 後端 API 與前端調用

[RabbirReaper]

重構目標

整理並統一訂單相關的後端 API 與前端調用邏輯,償還技術債,提升程式碼可維護性和一致性。

當前問題

1. API 不一致

   • 部分 API 使用 RESTful 風格,部分使用自定義路由
   • 參數格式不統一(有些用 query, 有些用 body)
   • 回應格式不一致

2. 函數職責不清

   • Service 層函數職責過大,包含多種邏輯
   • Controller 和 Service 邊界模糊
   • 工具函數散落在不同檔案

3. 前端調用混亂

   • API 調用散落在不同組件
   • 缺少統一的錯誤處理
   • 重複的邏輯未抽取

4. 命名不一致

   • 函數命名風格不統一
   • 變數命名語義不清
   • 缺少清晰的註解

重構範圍

後端檔案
```
server/
├── controllers/Order/
│ ├── orderCustomer.js # 客戶端訂單控制器
│ └── orderAdmin.js # 管理端訂單控制器
├── services/order/
│ ├── orderCreation.js # 訂單創建
│ ├── orderPayment.js # 訂單支付
│ ├── orderValidation.js # 訂單驗證
│ ├── orderUtils.js # 訂單工具
│ └── orderAdmin.js # 訂單管理
├── routes/
│ ├── orderCustomer.js # 客戶端路由
│ └── orderAdmin.js # 管理端路由
└── models/Order/
└── Order.js # 訂單模型
```

前端檔案
```
src/
├── api/modules/
│ └── order.js # 訂單 API 封裝
├── stores/
│ └── order.js # 訂單狀態管理
├── views/customer/
│ ├── CartView.vue # 購物車
│ └── OrderHistoryView.vue # 訂單歷史
└── components/counter/
└── OrderList.vue # POS 訂單列表
```

重構任務清單

後端重構

1. 統一 API 設計規範

• 制定 RESTful API 命名規範
• 統一請求參數格式(body vs query)
• 統一回應格式(success/error structure)
• 定義標準錯誤碼

2. Service 層重構

• 拆分過大的函數(單一職責原則)
• 統一函數命名規範
• 提取共用邏輯到 utils
• 改善錯誤處理機制
• 添加完整的 JSDoc 註解

3. Controller 層重構

• 簡化 controller 邏輯(只處理 HTTP)
• 統一參數驗證方式
• 統一錯誤回應格式
• 添加請求日誌

4. Route 層重構

• 重新組織路由結構
• 統一路由命名
• 檢查並修正權限中介層
• 添加路由文檔註解

5. 工具函數整理

• 將 `orderUtils.js` 中的函數分類
• 提取可重用的通用工具
• 移除重複代碼
• 添加單元測試

前端重構

1. API 調用層

• 統一所有訂單 API 到 `api/modules/order.js`
• 使用 TypeScript 或 JSDoc 定義介面
• 統一錯誤處理邏輯
• 添加 loading 狀態管理

2. 狀態管理

• 整合訂單相關 store
• 統一狀態更新邏輯
• 添加狀態持久化(必要時)
• 優化狀態訂閱機制

3. 組件重構

• 提取共用訂單組件
• 統一訂單顯示格式
• 優化大列表渲染效能
• 添加組件文檔

4. 流程優化

• 優化下單流程(減少步驟)
• 改善錯誤提示
• 添加載入狀態指示
• 優化行動端體驗

API 設計規範(建議)

客戶端 API
```
POST /api/orders # 創建訂單
GET /api/orders # 獲取訂單列表
GET /api/orders/:orderId # 獲取訂單詳情
PUT /api/orders/:orderId/cancel # 取消訂單
POST /api/orders/:orderId/payment # 訂單支付
```

管理端 API
```
GET /api/brands/:brandId/orders # 獲取品牌訂單
GET /api/brands/:brandId/stores/:storeId/orders # 獲取店鋪訂單
PUT /api/brands/:brandId/orders/:orderId/status # 更新訂單狀態
POST /api/brands/:brandId/orders/:orderId/refund # 訂單退款
```

實作策略

階段 1: 分析與規劃(1 週)

• 梳理現有 API 和函數
• 制定重構規範
• 識別高風險區域

階段 2: 後端重構(2-3 週)

• 先重構 Service 層(有測試保護)
• 再重構 Controller 層
• 最後調整 Route 層

階段 3: 前端重構(1-2 週)

• 重構 API 調用層
• 整合狀態管理
• 優化組件

階段 4: 測試與優化(1 週)

• 完善測試覆蓋
• 效能測試
• Bug 修復

風險控制

1. 使用 Feature Flag: 新舊 API 並存,逐步切換
2. 完善測試: 重構前確保測試覆蓋率
3. 小步提交: 每個小重構獨立提交
4. Code Review: 重構代碼需要仔細審查
5. 監控日誌: 上線後密切監控錯誤日誌

成功指標

• API 回應時間減少 20%
• 程式碼重複率降低 30%
• 測試覆蓋率提升至 80%
• Bug 數量減少
• 開發效率提升