DeliveryQuoteUtil 使用说明

简介

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

功能特性

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

使用方法

1. 引入命名空间

use common\components\delivery\helpers\DeliveryQuoteUtil;

2. 调用方法

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 中使用

// 生成随机订单号，不要跟原来的混起来，跑腿-销售单-
$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 中使用

// 准备商品列表
$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());
}

免费配送规则说明

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

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

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

错误处理

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

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

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

日志记录

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

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

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

注意事项

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

版本历史

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

DeliveryQuoteUtil_USAGE.md 6.2 KB Пермалинк Историја Датотека