Shipment Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/services/shipmentService.ts
• src/services/deliveryOrderService.ts
• src/schemas/shipment.ts
• prisma/schema.prisma
• src/services/spmbPdfService.ts
• comprehensive-swagger-api.json

Shipment Management is a core module within the Outmanage system responsible for coordinating the outbound logistics of goods. It manages the lifecycle of a shipment from creation—linking specific items from Delivery Orders (DOs)—through product selection, bulk or individual weighing, and finally to vehicle plate verification and completion. This module ensures that inventory levels are accurately tracked by moving quantities between pending, processing, and completed states.

The system supports two primary shipment types: ANTAR (Delivery) and JEMPUT (Pickup). It integrates with vehicle (Armada) management and driver assignments, while generating necessary legal and operational documentation such as SPMB (Surat Perintah Muat Barang) and weighing tickets (Nota Timbangan).

Sources: src/services/shipmentService.ts, prisma/schema.prisma:430-455

Shipment Lifecycle and Statuses

Shipments and their constituent items progress through a defined set of states. A shipment typically begins as PENDING, moves to PROSES once weighing or loading begins, and reaches SELESAI (Completed) after final verification.

Shipment States

Status	Description
PENDING	Initial state upon creation. Items are allocated from DOs but not yet loaded.
PROSES	Loading or weighing is underway for at least one item.
SELESAI	All items are weighed/completed and the vehicle plate has been verified.
CANCEL	The shipment has been cancelled, and quantities are returned to the DO.

Sources: prisma/schema.prisma:645-650, src/services/shipmentService.ts:1300-1350

Shipment Item States

Status	Description
PENDING	Item is assigned to a shipment but not yet selected for loading.
CHOSEN	Item has been selected for a specific loading group or weighing session.
COMPLETED	Item has been weighed and confirmed as loaded.
CANCELLED	Item was removed from the shipment.

Sources: prisma/schema.prisma:652-657, src/services/shipmentService.ts:850-880

The following flowchart illustrates the high-level shipment processing logic:

The diagram shows the sequence of operations from initial shipment creation to final completion.
Sources: src/services/shipmentService.ts:315-450, src/services/shipmentService.ts:1300-1400

Data Architecture

The shipment system relies on a complex relational model involving Delivery Orders, Products, Armadas, and Warehouses.

Core Entity Relationships

The ER diagram displays the central role of the Shipment entity and its dependencies on logistics and inventory data.
Sources: prisma/schema.prisma:430-550

Quantity Tracking Logic

When a shipment item is created or updated, the system performs atomic updates on the related DeliveryOrderItem to ensure data integrity and prevent double-allocating stock.

1. Creation: Moves quantity from pendingQuantity to processingQuantity in the DO.
2. Completion: Upon shipment verification, moves quantity from processingQuantity to completedQuantity.
3. Cancellation: Returns quantity from processingQuantity or completedQuantity back to pendingQuantity (depending on mode).

Sources: src/services/shipmentService.ts:380-410, src/services/shipmentService.ts:1320-1350, src/services/deliveryOrderService.ts:1250-1300

Weighing Operations

The system supports two weighing methods: MANUAL (often handled via bulk weighing) and VENDOR.

Bulk Weighing

Bulk weighing allows multiple shipment items sharing the same product to be weighed at once. The system calculates a proportional weight for each item based on its requested quantity relative to the total group weight.

The sequence shows how bulk weighing distributes a single scale reading across multiple shipment items.
Sources: src/services/shipmentService.ts:1380-1550

Weighing Configuration

Parameter	Type	Description
grossWeight	Float	The total weight of the loaded goods and vehicle/container.
tareWeight	Float	The weight of the empty vehicle/container.
netWeight	Float	Calculated as Gross - Tare (the actual goods weight).
loadingGroupId	String	Identifier for grouping items during a single loading session.

Sources: src/schemas/shipment.ts:140-165

Document Management

The Shipment Management module is responsible for the automated generation of PDF documents stored in the public directory.

SPMB (Surat Perintah Muat Barang)

SPMBs are generated for every unique combination of Delivery Order and Warehouse within a shipment. If a shipment contains items from three different DOs across two warehouses, multiple SPMBs are created to guide warehouse staff.

• Logic: Items are filtered by deliveryOrderId and warehouseId during generation.
• Update: If shipment items are modified or the tally is updated, existing SPMBs are deleted and regenerated to ensure accuracy.

Sources: src/services/spmbPdfService.ts:80-150, src/services/shipmentService.ts:450-520

Nota Timbangan (Weighing Ticket)

A Nota Timbangan is generated immediately after a weighing operation (individual or bulk) is finalized.

• Content: Includes ticket number, product details, weights (Gross/Net/Tare), and related DO numbers.
• Regeneration: If a DO is revised after weighing, the corresponding Nota Timbangan is recalculated and regenerated.

Sources: src/services/shipmentService.ts:1530-1550, src/services/deliveryOrderService.ts:1050-1100

Revision and Corrections

The system provides robust mechanisms for correcting errors even after shipments have progressed to weighing.

Change Customer After Weighing

Users can reassign a Delivery Order to a different customer after items have been weighed. This triggers a cascade of updates:

1. Updates the customerId on the DeliveryOrder record.
2. Regenerates all associated SPMB PDFs with the new customer name and address.
3. Regenerates all Nota Timbangan PDFs linked to those items.

Sources: src/services/deliveryOrderService.ts:850-950

Item Quantity Revision

If a truck is overloaded or a customer changes their order mid-loading, quantities can be revised.

• Increase: Allowed only if pendingQuantity is available in the DO.
• Decrease: Returns the difference to the DO's pending pool.
• Recalculation: Weight data is scaled proportionally (e.g., if quantity is halved, the recorded gross weight in the weighing record is also halved).

Sources: src/services/deliveryOrderService.ts:1000-1100, src/services/deliveryOrderService.ts:1450-1550

Conclusion

Shipment Management provides the critical bridge between sales (Delivery Orders) and physical fulfillment. By utilizing atomic database transactions and complex quantity recalculation logic, the system maintains a high degree of inventory accuracy. The integration of automated document generation and AI-ready plate verification streamlines the workflow for warehouse operators and drivers while providing management with detailed audit logs and operational reports.

Sources: src/services/shipmentService.ts:1-50, comprehensive-swagger-api.json:10-50