Tally & Loading Groups

Relevant source files

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

• src/services/shipmentService.ts
• src/services/deliveryOrderService.ts
• src/services/reportService.ts
• src/services/spmbPdfService.ts
• src/services/notaTimbanganPdfService.ts
• comprehensive-swagger-api.json

The Tally and Loading Groups systems within the Outmanage project manage the operational aspects of shipment preparation and weighing. Tally refers to the personnel or records responsible for verifying item counts during the loading process, while Loading Groups serve as a logical grouping mechanism to handle multiple items—often across different delivery orders—as a single unit for weighing and document generation.

These systems ensure that when a vehicle is loaded, items are tracked accurately from the warehouse to the fleet. The integration of loading groups allows the system to distribute weights proportionally across various delivery order items when bulk weighing is performed, maintaining data integrity across the shipment's lifecycle.

Loading Groups Architecture

Loading groups are dynamically generated when products are "chosen" for a shipment. A loadingGroupId is assigned to ShipmentItem records to link them together for subsequent weighing operations. This is particularly critical for the "Bulk Weighing" feature where a single weight measurement applies to multiple physical items of the same product type.

Loading Group Lifecycle

1. Product Selection: When a user selects a product for a shipment, the system identifies all pending ShipmentItem records for that product.
2. Group Generation: A unique ID (e.g., shipmentId-productId-timestamp) is generated and assigned to the items.
3. Status Transition: Items move from PENDING to CHOSEN status.
4. Weighing Correlation: During weighing, the system queries items by loadingGroupId to apply the measured weights.

Sources: src/services/shipmentService.ts:1340-1365, src/services/shipmentService.ts:1615-1630

The diagram above illustrates how items transition from delivery orders into logical loading groups within a shipment.
Sources: src/services/shipmentService.ts:1340-1370, src/services/shipmentService.ts:1410-1440

Tally Operations

The Tally system tracks the specific personnel or verification data associated with the loading of a shipment. Tally information is stored directly on the Shipment entity and is reflected in essential documents like the SPMB (Surat Perintah Muat Barang).

Tally Management Functions

Function	Description	Source File
updateTally	Updates the tally field for a shipment and triggers SPMB regeneration.	src/services/shipmentService.ts:1810-1880
generateSPMB	Includes tally information in the header of the generated PDF document.	src/services/spmbPdfService.ts:105-115

Document Synchronization

When a tally update occurs, the system automatically regenerates all SPMB documents associated with that shipment. This ensures that the physical papers carried by drivers always match the digital records in the system.

Sources: src/services/shipmentService.ts:1825-1870, src/services/spmbPdfService.ts:113

Bulk Weighing & Weight Distribution

One of the primary purposes of Loading Groups is to facilitate bulk weighing. Instead of weighing every item individually, the system allows for a single weighing record to be linked to a loading group.

Proportional Weight Logic

When a bulk weight is recorded for a loading group, the system calculates the distribution as follows:

1. Total Requested Quantity: Sum of requestedQuantity for all items in the group.
2. Proportion Calculation: itemProportion = itemRequestedQuantity / totalRequestedQuantity.
3. Weighted Quantity: itemWeightedQuantity = totalGrossWeight * itemProportion.

Sources: src/services/shipmentService.ts:1610-1660

This sequence shows the flow of data from a user request through the weight distribution logic and document generation.
Sources: src/services/shipmentService.ts:1605-1710

Data Models & Constraints

Loading Group Related Fields

Field	Type	Entity	Description
loadingGroupId	String	ShipmentItem	Unique ID linking items for bulk operations.
tally	String	Shipment	Name or ID of the person/entity verifying the load.
weighingMethod	Enum	ShipmentChosenProduct	Determines if weighing is handled by 'VENDOR' or internally.
chosenProduct	Boolean	ShipmentItem	Flag indicating the item is part of a loading group.

Sources: src/services/shipmentService.ts:1350-1365, comprehensive-swagger-api.json:1050-1100

Selective Loading Grouping

Unlike standard loading groups that take all items of a product, "Selective Loading" allows users to pick specific delivery orders. This creates a filtered loading group where only the items from selected DOs are transitioned to the CHOSEN status.

Sources: src/services/shipmentService.ts:1400-1450

API Endpoints

The following endpoints manage the interaction between tally, loading groups, and weighing:

Method	Endpoint	Description
POST	/api/shipments/weighing	Executes bulk weighing for a specific product/loading group.
GET	/api/shipments/available-items	Retrieves items grouped by product ready for loading groups.
PATCH	/api/shipments/{id}/tally	Updates the tally information for a shipment.
POST	/api/shipments/{id}/choosen-product	Marks products as "Chosen" and assigns them to a loading group.

Sources: comprehensive-swagger-api.json:1500-1650, src/services/shipmentService.ts:1340

Conclusion

The Tally & Loading Groups system provides the necessary logical structure to bridge the gap between abstract delivery orders and physical shipment logistics. By utilizing unique loading group identifiers, the platform handles complex scenarios like proportional weight distribution across multiple customers and ensures that documentation like the SPMB and Nota Timbangan remain synchronized with real-world loading activities verified by tally personnel.