README

微信小程序即时配送API集成组件，提供与微信小程序即时配送平台交互的能力，支持美团、闪送等多家配送服务提供商。

Features
Installation
Configuration
Usage
Advanced Usage
Architecture
Commands
API Reference
Security
Dependencies
Contributing
License

Features

配送公司管理: 同步和管理支持的配送服务提供商
账号绑定: 管理小程序与配送公司的绑定关系
订单操作: 支持完整的订单生命周期管理
查询功能: 实时查询订单状态和配送信息
测试支持: 提供模拟环境用于开发测试
命令行工具: 提供便捷的数据同步命令

Installation

composer require tourze/wechat-mini-program-express-bundle

如果使用Symfony Flex，Bundle会自动注册。否则，手动添加到 config/bundles.php：

return [
    // ... other bundles
    WechatMiniProgramExpressBundle\WechatMiniProgramExpressBundle::class => ['all' => true],
];

Configuration

Bundle无需额外配置，依赖于 WechatMiniProgramBundle 的配置。确保已正确配置微信小程序账号信息。

示例配置文件 config/packages/wechat_mini_program.yaml：

wechat_mini_program:
    default_account: 'your_default_account'
    accounts:
        your_account:
            app_id: 'your_app_id'
            secret: 'your_secret'

Usage

基本用法

1. 同步配送公司信息

# 同步所有配送公司信息
bin/console wechat-express:sync-delivery-companies

# 同步指定账号的配送公司信息
bin/console wechat-express:sync-delivery-companies --account-id=1

2. 同步绑定账号

# 同步所有绑定账号
bin/console wechat-express:sync-bind-accounts

# 同步指定账号的绑定信息
bin/console wechat-express:sync-bind-accounts --account-id=1

3. 下单流程

use WechatMiniProgramExpressBundle\Service\DeliveryOrderService;
use WechatMiniProgramExpressBundle\Request\PreAddOrderRequest;
use WechatMiniProgramExpressBundle\Request\AddOrderRequest;

// 获取服务
$deliveryOrderService = $this->container->get(DeliveryOrderService::class);

// 预下单获取配送费
$preOrderRequest = new PreAddOrderRequest();
$preOrderRequest->setAccount($account);
$preOrderRequest->setDeliveryId('delivery_company_id');
$preOrderRequest->setShopId('shop_id');
// ... 设置其他参数

$preOrderResponse = $deliveryOrderService->preAddOrder($preOrderRequest);

// 正式下单
$orderRequest = new AddOrderRequest();
$orderRequest->setAccount($account);
// ... 设置订单参数

$orderResponse = $deliveryOrderService->addOrder($orderRequest);

4. 查询订单

use WechatMiniProgramExpressBundle\Service\OrderQueryService;
use WechatMiniProgramExpressBundle\Request\GetOrderRequest;

$orderQueryService = $this->container->get(OrderQueryService::class);

$queryRequest = new GetOrderRequest();
$queryRequest->setAccount($account);
$queryRequest->setShopOrderId('your_order_id');

$orderInfo = $orderQueryService->getOrder($queryRequest);

Advanced Usage

自定义订单实体

use WechatMiniProgramExpressBundle\Entity\Order;
use WechatMiniProgramExpressBundle\Entity\Embed\SenderInfo;
use WechatMiniProgramExpressBundle\Entity\Embed\ReceiverInfo;

// 创建订单
$order = new Order();

// 设置发送方信息
$senderInfo = new SenderInfo();
$senderInfo->setName('发送方姓名');
$senderInfo->setCity('北京市');
$senderInfo->setAddress('详细地址');
$senderInfo->setPhone('联系电话');
$order->setSenderInfo($senderInfo);

// 设置接收方信息
$receiverInfo = new ReceiverInfo();
$receiverInfo->setName('接收方姓名');
$receiverInfo->setCity('上海市');
$receiverInfo->setAddress('详细地址');
$receiverInfo->setPhone('联系电话');
$order->setReceiverInfo($receiverInfo);

// 转换为请求参数
$requestParams = $order->toRequestArray();

事件监听

// 监听订单创建事件
class OrderCreatedListener
{
    public function onOrderCreated(OrderCreatedEvent $event): void
    {
        $order = $event->getOrder();
        // 处理订单创建后的业务逻辑
    }
}

Architecture

Bundle采用分层架构和服务职责分离原则：

graph TD
    A[WechatMiniProgramExpressBundle] --> B[DeliveryConfigService]
    A --> C[DeliveryOrderService]
    A --> D[OrderQueryService]
    A --> E[MockOrderService]

    B --> F[配送公司与绑定账号管理]
    C --> G[订单创建与修改]
    D --> H[订单查询与异常处理]
    E --> I[订单状态模拟更新]

    B -.依赖.-> J[WechatMiniProgramBundle]
    C -.依赖.-> J
    D -.依赖.-> J
    E -.依赖.-> J

核心服务

DeliveryConfigService: 配置管理服务

配送公司数据同步与管理
商户绑定账号信息维护

DeliveryOrderService: 订单操作服务

预下单、正式下单
订单取消、重新下单

OrderQueryService: 查询服务

订单状态查询
异常处理

MockOrderService: 测试服务（仅测试环境）

模拟订单状态更新

Commands

同步配送公司列表

bin/console wechat-express:sync-delivery-companies [--account-id=<account_id>]

同步支持的配送公司信息到本地数据库。

参数:

--account-id: 可选，指定同步特定账号的配送公司信息

同步绑定账号信息

bin/console wechat-express:sync-bind-accounts [--account-id=<account_id>]

同步已绑定的配送账号信息。

参数:

--account-id: 可选，指定同步特定账号的绑定信息

API Reference

本Bundle集成以下微信小程序即时配送API：

Security

在使用本Bundle时，请注意以下安全事项：

API密钥保护: 确保微信小程序的AppSecret等敏感信息安全存储，不要硬编码在代码中
数据传输安全: 所有与微信API的通信都通过HTTPS进行
订单数据保护: 订单中可能包含用户隐私信息，请确保符合数据保护法规
访问控制: 实施适当的权限控制，确保只有授权用户可以操作配送订单

Dependencies

tourze/wechat-mini-program-bundle: 微信小程序基础包
symfony/framework-bundle: Symfony框架核心
doctrine/orm: Doctrine ORM

Contributing

欢迎贡献代码！请确保：

遵循项目的编码规范
编写相应的测试用例
更新相关文档
提交前运行测试确保通过

License

This project is licensed under the MIT License - see the LICENSE file for details.

tourze / wechat-mini-program-express-bundle

Maintainers

Details