實作外送距離價格計算功能

[RabbirReaper]

功能描述

需要實作根據外送距離計算配送費用的功能,為不同距離區間設定不同的價格。

需求分析

基本功能

1. 設定店家配送範圍(最大配送距離)
2. 設定距離階梯定價規則
3. 根據客戶地址計算配送距離
4. 自動計算並添加配送費用到訂單

進階功能

1. 支援免運費門檻(滿額免運)
2. 不同時段不同配送費率
3. 配送黑名單區域
4. 預估配送時間

資料模型設計

Store 模型擴展
```javascript
// server/models/Store/Store.js
deliverySettings: {
enabled: Boolean,
maxDistance: Number, // 最大配送距離(公里)
distancePricing: [{
minDistance: Number, // 起始距離(公里)
maxDistance: Number, // 結束距離(公里)
price: Number // 配送費用(元)
}],
freeDeliveryThreshold: Number, // 免運門檻(元)
coordinates: {
lat: Number,
lng: Number
}
}
```

Order 模型擴展
```javascript
// server/models/Order/Order.js
deliveryInfo: {
address: String,
coordinates: {
lat: Number,
lng: Number
},
distance: Number, // 配送距離(公里)
deliveryFee: Number, // 配送費用
freeDeliveryApplied: Boolean
}
```

距離計算方法

選項 1: Haversine 公式(簡單快速)
```javascript
// server/utils/distanceCalculator.js
export const calculateDistance = (lat1, lon1, lat2, lon2) => {
const R = 6371 // 地球半徑(公里)
const dLat = toRad(lat2 - lat1)
const dLon = toRad(lon2 - lon1)
const a =
Math.sin(dLat/2) * Math.sin(dLat/2) +
Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) *
Math.sin(dLon/2) * Math.sin(dLon/2)
const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
return R * c // 距離(公里)
}
```

選項 2: Google Maps Distance Matrix API(準確但需費用)

• 考慮實際路線距離
• 考慮交通狀況
• 提供預估時間

API 端點設計

店家管理端
```
PUT /api/brands/:brandId/stores/:storeId/delivery-settings
GET /api/brands/:brandId/stores/:storeId/delivery-settings
```

客戶端
```
POST /api/stores/:storeId/calculate-delivery-fee
Body: { address: string, coordinates: { lat, lng }, orderTotal: number }
Response: {
distance: number,
deliveryFee: number,
freeDeliveryApplied: boolean,
canDeliver: boolean
}
```

前端整合點

設定介面

• `src/components/BrandAdmin/Store/DeliverySettings.vue` (新建)
• 設定配送範圍、距離定價、免運門檻

客戶下單流程

• `src/views/customer/CartView.vue` - 添加地址輸入和配送費顯示
• 輸入地址後自動計算配送費
• 顯示是否在配送範圍內

實作步驟

• 擴展 Store 和 Order 資料模型
• 實作距離計算工具函數
• 實作配送費計算服務
• 建立店家設定 API
• 建立配送費計算 API
• 實作前端設定介面
• 整合到下單流程
• 撰寫單元測試
• 撰寫 E2E 測試
• 文檔更新

技術考量

地址轉座標

• 整合 Google Geocoding API 或台灣內政部地址服務
• 快取常用地址的座標

效能優化

• 快取距離計算結果
• 使用簡單的 Haversine 公式做初步過濾

錯誤處理

• 地址無法解析時的處理
• 超出配送範圍的提示

測試案例

1. 不同距離區間的配送費計算
2. 免運門檻的觸發
3. 超出配送範圍的拒絕
4. 座標無效的錯誤處理
5. 同一地址的快取效果