Delivery Order Management
Relevant source files
The following files were used as context for generating this wiki page:
Delivery Order (DO) Management is a core module of the Outmanage system responsible for coordinating customer orders with warehouse inventory and outbound logistics. It serves as the primary link between customers and the products they receive, tracking the entire lifecycle of an order from initial pending status through shipment processing to final completion.
The system emphasizes granular quantity tracking across multiple states (pending, processing, completed, and cancelled) to ensure accurate inventory control during the weighing and shipping phases. It also provides advanced post-shipment capabilities such as item transfers between customers and proportional weight recalculations when order quantities are revised after scale operations.
Core Architecture and Data Model
The Delivery Order system is built on a hierarchical relationship between Customers, Delivery Orders, and Delivery Order Items. Each order is identified by a unique, auto-generated alphanumeric code and contains one or more product items with specific quantity requirements.
Entity Relationships
The following diagram illustrates how Delivery Orders interact with inventory and logistics entities:
Quantity Tracking Logic
Each DeliveryOrderItem maintains five distinct quantity fields to track fulfillment progress:
- Total Quantity: The original amount requested.
- Pending Quantity: Amount available to be assigned to new shipments.
- Processing Quantity: Amount currently assigned to active (incomplete) shipments.
- Completed Quantity: Amount successfully weighed and verified in finished shipments.
- Cancelled Quantity: Amount removed from the order or returned to inventory.
Sources: src/services/deliveryOrderService.ts:1450-1500, comprehensive-swagger-api.json:545-565
Delivery Order Lifecycle
Delivery Orders progress through several statuses based on the state of their constituent items and related shipments.
Status Transitions
The status transitions are primarily driven by the processingQuantity and completedQuantity fields of the order's items.
Order Creation Process
When a DO is created, the system validates the customer's existence and ensures no duplicate products are listed within the same order. A unique 6-character NanoID is generated as the doNumber.
Advanced Operations
The system provides specialized endpoints for handling complex logistical scenarios that occur after an order has entered the processing or completion stage.
Transfer Items to New Customer
This feature allows administrators to move completed items from an existing shipment's DO to a new customer. This is useful for correcting misrouted shipments or handling secondary sales.
- Source: A completed shipment (
STATUS.SELESAI). - Action: Reduces quantity from the original DO and creates a new DO for the target customer.
- Recalculation: The system automatically generates new proportional weighing records and Nota Timbangan PDFs for the transferred items.
Sources: src/services/deliveryOrderService.ts:1050-1150, src/controllers/deliveryOrderController.ts:580-620
Post-Weighing Revisions
If an order's quantity must change after weighing (e.g., due to truck overloading), the system performs a proportional recalculation:
- Ratio Calculation:
New Quantity / Old Quantity. - Weight Adjustment: Existing weighing records (gross/net weight) are scaled by the ratio.
- Document Regeneration: SPMB (Surat Perintah Muat Barang) and Nota Timbangan PDFs are automatically deleted and regenerated with corrected data.
Sources: src/services/deliveryOrderService.ts:850-950, src/services/shipmentService.ts:1650-1700
API Reference Summary
| Endpoint | Method | Description | Key Parameters |
|---|---|---|---|
/api/delivery-orders | GET | List orders with pagination/search | page, limit, status, search |
/api/delivery-orders | POST | Create a new order | customerId, items[] |
/api/delivery-orders/{id} | PUT | Update order details (if not finished) | address, items[] |
/api/delivery-orders/transfer-items | POST | Transfer items between customers | targetCustomerId, sourceShipmentId |
/api/delivery-orders/reduce-quantity | POST | Reduce item quantity post-shipment | shipmentItemId, newQuantity |
/api/delivery-orders/{id}/restore | PATCH | Restore a soft-deleted order | id |
Sources: comprehensive-swagger-api.json:480-1050, src/controllers/deliveryOrderController.ts:20-650
Implementation Details
Quantity Validation Middleware
The deliveryOrderController enforces strict rules during updates to prevent data corruption:
- Items cannot be deleted if they have any
processing,completed, orcancelledquantity. - The total quantity of an item cannot be reduced below the sum of its currently used quantities (
processing + completed + cancelled).
Sources: src/controllers/deliveryOrderController.ts:260-300
Transaction Integrity
All DO operations, especially revisions and transfers, are wrapped in Prisma transactions to ensure that quantity updates in DeliveryOrderItem stay in sync with ShipmentItem and weighing records. For example, when a shipment item is cancelled, the quantity is returned to the DO's pendingQuantity within the same database atomic block.
Sources: src/services/deliveryOrderService.ts:1400-1450, src/services/shipmentService.ts:1800-1850
Conclusion
Delivery Order Management provides a robust framework for managing the lifecycle of customer requests within the outbound logistics pipeline. By utilizing multi-state quantity tracking and proportional weight recalculation, the system maintains high data integrity even when operational requirements change mid-process. Its integration with automated PDF generation and shipment logging ensures that all physical movements are backed by accurate digital documentation.