README

English | 中文

Symfony bundle for managing delivery orders and stock tracking in e-commerce applications.

Features

• Delivery Order Management: Create, track, and manage delivery orders with multiple status states
• Stock Item Tracking: Track individual SKUs within delivery orders with batch/serial number support
• Status Workflow: Complete status lifecycle (pending → shipped → received/rejected)
• EasyAdmin Integration: Built-in admin controllers for order and stock management
• OMS Integration: Sync delivery information from external Order Management Systems
• Express Tracking: Support for express delivery company integration
• Flexible Source Types: Handle orders from multiple sources (purchase orders, sales orders, etc.)

Installation

composer require tourze/deliver-order-bundle

Register the bundle in config/bundles.php:

<?php

return [
    // ...
    DeliverOrderBundle\DeliverOrderBundle::class => ['all' => true],
];

Quick Start

Creating a Delivery Order

<?php

use DeliverOrderBundle\Entity\DeliverOrder;
use DeliverOrderBundle\Entity\DeliverStock;
use DeliverOrderBundle\Enum\DeliverOrderStatus;
use DeliverOrderBundle\Enum\SourceType;
use DeliverOrderBundle\Service\DeliveryService;

// Inject the delivery service
/** @var DeliveryService $deliveryService */

// Create delivery context
$order = new DeliverOrder();
$order->setSn('DO-2025-001')
    ->setSourceType(SourceType::PURCHASE_ORDER)
    ->setSourceId('PO-123')
    ->setConsigneeName('John Doe')
    ->setConsigneePhone('13800138000')
    ->setConsigneeAddress('123 Main St, City, State 12345')
    ->setStatus(DeliverOrderStatus::PENDING);

// Add stock items
$stock = new DeliverStock();
$stock->setSkuId('SKU001')
    ->setSkuCode('PROD-001')
    ->setSkuName('Product Name')
    ->setQuantity(10)
    ->setBatchNo('BATCH-001');

$order->addDeliverStock($stock);

// Save using the delivery service
$deliveryService->syncDeliveryFromOms($deliveryData);

Updating Delivery Status

<?php

use DeliverOrderBundle\Service\DeliverOperationService;

/** @var DeliverOperationService $operationService */

// Mark delivery as received
$operationService->markAllDeliveryAsReceived('DO-2025-001', 'user123');

// Check delivery status
$isFullyDelivered = $operationService->isContractFullyDelivered('PO-123');

Using Calculation Services

<?php

use DeliverOrderBundle\Service\DeliveryQuantityCalculator;
use DeliverOrderBundle\Service\DeliveryTimeCalculator;

/** @var DeliveryQuantityCalculator $quantityCalculator */
/** @var DeliveryTimeCalculator $timeCalculator */

// Calculate delivered quantities
$totalQuantity = $quantityCalculator->calculateContractTotalQuantity($products);
$deliveredQuantity = $quantityCalculator->calculateDeliveredQuantityForSku('PO-123', 'SKU001');

// Calculate delivery times
$firstDeliveryTime = $timeCalculator->calculateFirstDeliveryTime($orders);
$lastDeliveryTime = $timeCalculator->calculateLastDeliveryTime($orders);

Entity Overview

DeliverOrder

Main delivery order entity with following key fields:

• sn: Unique delivery order number
• sourceType: Source system type (purchase order, sales order, etc.)
• sourceId: ID in the source system
• status: Current status (pending/shipped/received/rejected)
• expressCompany/expressCode/expressNumber: Express delivery tracking info
• consignee*: Recipient information

DeliverStock

Stock items within a delivery order:

• skuId/skuCode/skuName: Product identification
• quantity: Delivered quantity
• batchNo/serialNo: Tracking numbers
• received: Whether item was received
• receivedAt: Receipt timestamp

Status Workflow

PENDING → SHIPPED → RECEIVED
              ↓
           REJECTED

• PENDING (待发货): Order created, awaiting shipment
• SHIPPED (已发货): Order dispatched with express tracking
• RECEIVED (已收货): Order successfully delivered and accepted
• REJECTED (已拒收): Order delivered but rejected by recipient

Configuration

The bundle registers services automatically. Key services include:

• DeliverOrderBundle\Service\DeliveryService: Core delivery operations
• DeliverOrderBundle\Service\DeliverOperationService: Status management
• DeliverOrderBundle\Service\DeliveryQuantityCalculator: Quantity calculations
• DeliverOrderBundle\Service\DeliveryTimeCalculator: Time-based calculations

Admin Interface

The bundle provides EasyAdmin controllers for:

• /admin/deliver-order: Delivery order management
• /admin/deliver-stock: Stock item management

API Integration

OMS Sync Procedure

<?php

use DeliverOrderBundle\Procedure\SyncDeliveryInfoFromOms;

/** @var SyncDeliveryInfoFromOms $syncProcedure */

$result = $syncProcedure->execute([
    'sn' => 'DO-2025-001',
    'sourceType' => 'purchase_order',
    'sourceId' => 'PO-123',
    'consigneeName' => 'John Doe',
    'items' => [
        [
            'skuId' => 'SKU001',
            'quantity' => 10,
            'batchNo' => 'BATCH-001'
        ]
    ]
]);

Contributing

Please see CONTRIBUTING.md for details.

License

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