README

English | 中文

A Symfony bundle for managing WeChat Mini Program delivery return orders. This bundle provides entities, services, and console commands for handling return orders within WeChat Mini Program ecosystem.

Table of Contents

• Features
• Installation
• Dependencies
• Quick Start
  • 1. Enable the Bundle
  • 2. Configure Database
  • 3. Configure Services
  • 4. Basic Usage
• Core Components
  • Entities
  • Services
  • Commands
  • Event Subscribers
  • Repositories
  • Enums
  • Request Objects
• Configuration
• Advanced Usage
  • Return Order Management
  • Event Handling
  • Custom Extensions
• Console Commands
• API Reference
• Testing
• Contributing
• Security
• Changelog
• License

Features

• Entity Management: Complete entity structure for delivery return orders
• Service Layer: Service for synchronizing return order status with WeChat API
• Console Commands: Commands for manual and automated return order synchronization
• Event Handling: Event subscribers for return order processing
• Repository Pattern: Custom repository for efficient data access
• Enum Support: Type-safe enums for return order statuses
• API Integration: Request/response objects for WeChat API communication

Installation

composer require tourze/wechat-mini-program-delivery-return-bundle

Dependencies

This bundle requires:

• PHP 8.1 or higher
• Symfony 6.4 or higher
• Doctrine ORM
• WeChat Mini Program Bundle

Quick Start

1. Enable the Bundle

Add the bundle to your config/bundles.php:

<?php

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

2. Create a Return Order

<?php

use WechatMiniProgramDeliveryReturnBundle\Entity\DeliveryReturnOrder;
use WechatMiniProgramDeliveryReturnBundle\Service\DeliveryReturnService;

// Create a new return order
$returnOrder = new DeliveryReturnOrder();
$returnOrder->setShopOrderId('ORDER_123456');
$returnOrder->setOpenId('user_openid');
$returnOrder->setOrderPrice(9999); // Price in cents
$returnOrder->setBizAddress([
    'province' => 'Guangdong',
    'city' => 'Shenzhen',
    'area' => 'Nanshan',
    'street' => 'Tencent Building'
]);
$returnOrder->setUserAddress([
    'province' => 'Beijing',
    'city' => 'Beijing',
    'area' => 'Chaoyang',
    'street' => 'User Address'
]);

// Persist the order
$entityManager->persist($returnOrder);
$entityManager->flush();

3. Sync Return Order Status

<?php

use WechatMiniProgramDeliveryReturnBundle\Service\DeliveryReturnService;

// Inject the service
$deliveryReturnService = $container->get(DeliveryReturnService::class);

// Sync a specific return order
$deliveryReturnService->syncReturnOrder($returnOrder);

Console Commands

Sync Single Return Order

Synchronize a single return order by shop order ID:

php bin/console wechat-delivery-return:sync-single-return-order ORDER_123456

Parameters:

• shopOrderId: The shop order ID to synchronize

Sync Valid Return Orders

Automatically synchronize all valid return orders (runs every 15 minutes via cron):

php bin/console wechat-delivery-return:sync-valid-return-orders

This command:

• Finds all non-cancelled return orders created within the last 15 days (configurable via WECHAT_DELIVERY_RETURN_SYNC_RETURN_ORDER_DAY_NUM environment variable)
• Dispatches asynchronous sync commands for each order
• Runs automatically every 15 minutes via cron job

Advanced Usage

Event Handling

The bundle provides event subscribers for custom processing:

<?php

use WechatMiniProgramDeliveryReturnBundle\Event\ReturnOrderSyncedEvent;

// Listen for return order sync events
$eventDispatcher->addListener(ReturnOrderSyncedEvent::class, function (ReturnOrderSyncedEvent $event) {
    $returnOrder = $event->getReturnOrder();
    // Handle the synchronized return order
});

Custom Repository Methods

Access custom repository methods for advanced queries:

<?php

use WechatMiniProgramDeliveryReturnBundle\Repository\DeliveryReturnOrderRepository;

// Get return orders by status
$repository = $entityManager->getRepository(DeliveryReturnOrder::class);
$pendingOrders = $repository->findByStatus(DeliveryReturnStatus::Waiting);

// Get return orders within date range
$recentOrders = $repository->findRecentOrders(15); // Last 15 days

Configuration

Environment Variables

Configure the following environment variables:

# Number of days to look back for return orders (default: 15)
WECHAT_DELIVERY_RETURN_SYNC_RETURN_ORDER_DAY_NUM=15

Services

The bundle registers the following services:

• DeliveryReturnService: Main service for return order operations
• DeliveryReturnOrderRepository: Repository for return order data access
• Console commands for manual and automated synchronization

API Integration

The bundle provides request/response objects for WeChat API integration:

Request Objects

• AddRequest: For creating new return orders
• QueryStatusRequest: For querying return order status
• UnbindRequest: For unbinding return orders
• AddressObject: For handling address information

Response Handling

The service automatically handles API responses and updates local entities with:

• Return order status
• Waybill ID
• Delivery company information
• Order status updates

Database Schema

The bundle creates the following database table:

-- Table: wechat_mini_program_delivery_return_order
-- Columns include:
-- - id (snowflake ID)
-- - shop_order_id (unique shop order identifier)
-- - account_id (WeChat account reference)
-- - biz_address (JSON field for business address)
-- - user_address (JSON field for user address)
-- - open_id (WeChat user identifier)
-- - order_path (mini program order path)
-- - goods_list (JSON field for goods information)
-- - order_price (price in cents)
-- - return_id (WeChat return ID)
-- - waybill_id (logistics waybill ID)
-- - status (return status enum)
-- - order_status (order status enum)
-- - delivery_name (logistics company name)
-- - delivery_id (logistics company ID)
-- - create_time, update_time (timestamps)

Status Enums

DeliveryReturnStatus

• Represents the return order status from WeChat API

DeliveryReturnOrderStatus

• Represents the logistics order status
• Cancelled: Order has been cancelled

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.