huahuibao_document/任务小笔记/25-0811：微信小程序同城配送集成指南.md

微信小程序同城配送集成指南

概述

IntraCityExpress 类提供了微信小程序同城配送功能的完整实现，包括门店管理、订单管理、运力管理等功能。

功能特性

• ✅ 门店管理（创建、更新、删除、查询）
• ✅ 订单管理（创建、取消、查询）
• ✅ 运力管理（获取运力列表、服务范围）
• ✅ 回调处理（订单状态变化通知）
• ✅ 签名验证（微信API安全验证）
• ✅ 错误处理（完整的错误码处理）
• ✅ 测试支持（模拟回调接口）

安装配置

1. 小程序配置

在小程序管理后台开通同城配送功能：

1. 登录 微信公众平台
2. 进入小程序管理后台
3. 功能 -> 物流服务 -> 同城配送
4. 按照指引完成开通

2. 项目配置

在项目配置文件中添加同城配送相关配置：

// config/params.php
return [
    // 同城配送安全token（在小程序管理后台设置）
    'wx_intracity_token' => 'your_token_here',
    
    // 其他配置...
];

使用方法

1. 门店管理

创建门店

use common\components\IntraCityExpress;

$storeData = [
    'out_store_id' => 'store_001',
    'store_name' => '花店总店',
    'store_address' => '北京市朝阳区建国路88号',
    'store_longitude' => 116.397128,
    'store_latitude' => 39.916527,
    'store_phone' => '010-12345678',
    'service_type' => 1, // 同城配送
];

$result = IntraCityExpress::createStore($storeData);
if ($result['errcode'] === 0) {
    echo "门店创建成功";
} else {
    echo "门店创建失败：" . $result['errmsg'];
}

查询门店

$storeInfo = IntraCityExpress::getStore('store_001');
if ($storeInfo['errcode'] === 0) {
    print_r($storeInfo);
}

更新门店

$updateData = [
    'out_store_id' => 'store_001',
    'store_name' => '花店总店（已更新）',
    'store_address' => '北京市朝阳区建国路88号',
    'store_longitude' => 116.397128,
    'store_latitude' => 39.916527,
    'store_phone' => '010-87654321',
];

$result = IntraCityExpress::updateStore($updateData);

2. 订单管理

创建订单

$orderData = [
    'out_store_id' => 'store_001',
    'out_order_id' => 'order_' . time(),
    'delivery_service_code' => 'DADA', // 达达配送
    'to_user_name' => '张三',
    'to_user_phone' => '13800138000',
    'to_user_address' => '北京市海淀区中关村大街1号',
    'to_user_longitude' => 116.307852,
    'to_user_latitude' => 39.984154,
    'goods_value' => 10000, // 商品价值（分）
    'goods_weight' => 1000, // 商品重量（克）
    'goods_pickup_info' => '鲜花一束',
    'goods_delivery_info' => '鲜花一束',
    'goods_type' => IntraCityExpress::GOODS_TYPE_FLOWER, // 鲜花
    'expected_pickup_time' => date('Y-m-d H:i:s', time() + 1800), // 30分钟后取货
    'expected_delivery_time' => date('Y-m-d H:i:s', time() + 7200), // 2小时后送达
];

$result = IntraCityExpress::createOrder($orderData);
if ($result['errcode'] === 0) {
    $wxOrderId = $result['wx_order_id'];
    echo "订单创建成功，微信订单号：" . $wxOrderId;
}

查询订单

// 通过微信订单号查询
$orderInfo = IntraCityExpress::getOrder($wxOrderId);

// 通过商户订单号查询
$orderInfo = IntraCityExpress::getOrder('', $outOrderId);

// 通过门店订单号查询
$orderInfo = IntraCityExpress::getOrder('', '', $outStoreId);

取消订单

$result = IntraCityExpress::cancelOrder($wxOrderId);

获取订单列表

$orderList = IntraCityExpress::getOrderList(0, 20);

4. 回调处理

设置回调URL

在小程序管理后台设置回调URL：https://your-domain.com/intra-city/callback

处理回调

// 在控制器中处理回调
public function actionCallback()
{
    $callbackData = Yii::$app->request->post();
    $token = Yii::$app->params['wx_intracity_token'];
    
    $result = IntraCityExpress::handleOrderCallback($callbackData, $token);
    
    // 返回处理结果
    Yii::$app->response->format = Response::FORMAT_JSON;
    return $result;
}

5. 测试功能

模拟回调

$result = IntraCityExpress::mockNotify(
    IntraCityExpress::ORDER_STATUS_ACCEPTED, // 配送员接单
    $wxOrderId
);

API 接口说明

门店管理接口

接口	方法	说明
/intra-city/create-store	POST	创建门店
/intra-city/update-store	POST	更新门店
/intra-city/get-store	GET	查询门店

订单管理接口

接口	方法	说明
/intra-city/create-order	POST	创建订单
/intra-city/get-order	GET	查询订单
/intra-city/cancel-order	POST	取消订单

其他接口

接口	方法	说明
/intra-city/callback	POST	微信回调接口
/intra-city/mock-notify	POST	模拟回调（测试用）

错误处理

常见错误码

错误码	说明	解决方案
934000	其他逻辑错误	检查请求参数和业务逻辑
934001	请求参数有误	检查必填参数是否完整
934002	订单已存在，且订单在处理中	避免重复创建订单
934003	运力ID错误	检查运力配置是否正确
934008	门店ID和APPID不匹配	检查门店配置
934009	不支持该门店所在城市	联系微信客服
934011	请求签名错误	检查签名算法和token
934012	appid和access_token不匹配	检查小程序配置
934013	门店余额不足无法下单	充值门店余额
934016	订单不存在	检查订单ID是否正确
934019	超出运力支持的配送范围	选择其他配送方式
934020	商品超重	检查商品重量限制
934021	门店不存在	先创建门店

错误处理示例

try {
    $result = IntraCityExpress::createOrder($orderData);
    
    if ($result['errcode'] !== 0) {
        switch ($result['errcode']) {
            case 934021:
                echo "门店不存在，请先创建门店";
                break;
            case 934003:
                echo "运力ID错误，请检查运力配置";
                break;
            case 934019:
                echo "超出配送范围，请选择其他配送方式";
                break;
            default:
                echo "其他错误，请联系技术支持";
                break;
        }
    }
} catch (\Exception $e) {
    echo "系统异常：" . $e->getMessage();
}

注意事项

1. 安全token配置：确保在小程序管理后台正确设置安全token
2. 回调URL配置：回调URL必须使用HTTPS协议
3. 参数验证：所有必填参数都必须提供
4. 错误处理：妥善处理各种错误情况
5. 日志记录：记录重要的操作日志
6. 测试环境：在沙箱环境充分测试后再上线

相关文档

• 微信小程序同城配送官方文档
• 微信服务端API签名指南