# DeliveryQuoteUtil 使用说明

## 简介

`DeliveryQuoteUtil` 是一个统一的配送报价工具类，用于处理跑腿平台报价、免费配送规则等逻辑。

## 功能特性

- ✅ 自动计算商品总重量
- ✅ 调用跑腿平台获取报价（支持闪送、货拉拉、蜂鸟、顺丰、达达等）
- ✅ 自动重试机制
- ✅ 应用免费配送规则
- ✅ 统一的异常处理
- ✅ 详细的日志记录

## 使用方法

### 1. 引入命名空间

```php
use common\components\delivery\helpers\DeliveryQuoteUtil;
```

### 2. 调用方法

```php
try {
    $quoteResult = DeliveryQuoteUtil::getDeliveryQuote([
        'productList' => $productList,           // 商品列表
        'deliveryPlatform' => $platform,         // 配送平台
        'ghsInfo' => $ghsInfo,                   // 供货商信息
        'custom' => $custom,                     // 客户信息对象
        'order' => [                             // 订单信息
            'orderSn' => $orderSn,
            'itemTotalAmount' => $totalAmount,
            'remark' => $remark,
        ],
        'mainId' => $this->mainId,               // 当前操作者 mainId
        'productCount' => $productCount,         // 商品总数量
    ]);
    
    // 获取结果
    $sendCost = $quoteResult['sendCost'];           // 配送费用（元）
    $sendDistance = $quoteResult['sendDistance'];   // 配送距离（米）
    $deliveryList = $quoteResult['deliveryList'];   // 可选配送方式列表
    
} catch (\Exception $e) {
    util::fail($e->getMessage());
}
```

## 参数说明

### 输入参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| productList | array | 是 | 商品列表，每项包含 `bigNum`（数量）和 `weight`（重量） |
| deliveryPlatform | string | 是 | 配送平台：`shansong`/`huolala`/`fengniao`/`shunfeng`/`dada` |
| ghsInfo | array | 是 | 供货商信息，包含 `mainId` 和 `shopId` |
| custom | object | 是 | 客户信息对象，包含 `name`, `mobile`, `fullAddress`, `lat`, `long` 等 |
| order | array | 是 | 订单信息，包含 `orderSn`, `itemTotalAmount`, `remark` |
| mainId | int | 是 | 当前操作者的 mainId |
| productCount | int | 否 | 商品总数量（用于免费配送规则判断） |

### 返回结果

| 字段名 | 类型 | 说明 |
|--------|------|------|
| sendCost | float | 配送费用（元），已应用免费配送规则 |
| sendDistance | int | 配送距离（米） |
| deliveryList | array | 可选配送方式列表 |
| platformQuotes | array | 原始平台报价数据 |

## 使用示例

### 示例 1：在 PurchaseController 中使用

```php
// 生成随机订单号，不要跟原来的混起来，跑腿-销售单-
$prefix = 'PT-XSD-' . $this->mainId . '-';
$orderSn = $prefix . round(microtime(true) * 1000);

// 获取配送报价
try {
    $quoteResult = DeliveryQuoteUtil::getDeliveryQuote([
        'productList' => $productList,
        'deliveryPlatform' => $post['deliveryPlatform'],
        'ghsInfo' => $ghsInfo,
        'custom' => $custom,
        'order' => [
            'orderSn' => $orderSn,
            'itemTotalAmount' => $post['itemTotalAmount'] ?? 0,
            'remark' => $post['remark'] ?? '',
        ],
        'mainId' => $this->mainId,
        'productCount' => $productCount,
    ]);
    
    $sendCost = $quoteResult['sendCost'];
    $sendDistance = $quoteResult['sendDistance'];
    
} catch (\Exception $e) {
    util::fail($e->getMessage());
}
```

### 示例 2：在 OrderController 中使用

```php
// 准备商品列表
$productList = [];
foreach ($orderItems as $item) {
    $productList[] = [
        'bigNum' => $item['num'],
        'weight' => $item['weight'],
    ];
}

// 准备客户信息对象
$custom = (object)[
    'name' => $customName,
    'mobile' => $customMobile,
    'fullAddress' => $fullAddress,
    'floor' => $floor,
    'dist' => $dist,
    'lat' => $lat,
    'long' => $long,
    'address' => $address,
    'city' => $city,
];

// 获取配送报价
try {
    $quoteResult = DeliveryQuoteUtil::getDeliveryQuote([
        'productList' => $productList,
        'deliveryPlatform' => 'shansong',
        'ghsInfo' => [
            'mainId' => $shop->mainId,
            'shopId' => $shop->id,
        ],
        'custom' => $custom,
        'order' => [
            'orderSn' => $orderSn,
            'itemTotalAmount' => $totalAmount,
            'remark' => $remark,
        ],
        'mainId' => $this->mainId,
        'productCount' => $totalCount,
    ]);
    
    $sendCost = $quoteResult['sendCost'];
    $sendDistance = $quoteResult['sendDistance'];
    
} catch (\Exception $e) {
    util::fail('获取配送报价失败：' . $e->getMessage());
}
```

## 免费配送规则说明

工具类会自动应用以下免费配送规则：

1. **基础免费距离**：如果配送距离在店铺设置的 `hcFreeKm` 范围内，免收配送费
2. **条件免费配送**：超过基础免费距离后，如果满足以下条件，仍可免费：
   - 商品数量 >= 规则设定数量
   - 商品总金额 >= 规则设定金额
   - 配送距离 <= 规则设定距离

这些规则从 `xh_shop_ext` 表的 `hcFreeKm` 和 `hcMap` 字段中读取。

## 错误处理

工具类会在以下情况抛出异常：

- 缺少必要参数
- 商品列表为空
- 供货商信息不完整
- 供货商店铺不存在
- 平台报价接口调用失败
- 没有可用的配送方式

建议使用 `try-catch` 捕获异常并给用户友好的提示。

## 日志记录

工具类会自动记录以下日志：

- 平台报价接口调用失败
- 免费配送规则命中情况
- 异常信息

日志通过 `Yii::error()` 和 `noticeUtil::push()` 记录。

## 注意事项

1. 确保传入的 `custom` 对象包含完整的地址和经纬度信息
2. `productList` 中每个商品必须包含 `bigNum` 和 `weight` 字段
3. 配送平台名称必须是小写英文：`shansong`/`huolala`/`fengniao`/`shunfeng`/`dada`
4. 工具类内置重试机制，第一次失败会自动重试一次
5. 返回的 `sendCost` 单位是元，`sendDistance` 单位是米

## 版本历史

- **v1.0.0** (2024-12-04)
  - 初始版本
  - 支持闪送、货拉拉、蜂鸟、顺丰、达达平台
  - 支持免费配送规则
  - 支持自动重试机制