Weighing & Scales
Relevant source files
The following files were used as context for generating this wiki page:
The Weighing & Scales module is a core component of the Outmanage outbound logistics system. It handles the critical transition of shipment items from a "CHOSEN" state to a "COMPLETED" state by recording precise weight measurements. The system supports multiple weighing workflows, including manual entry by internal staff and bulk automated entry via third-party vendor APIs.
This module ensures that weights are distributed proportionally across multiple delivery order (DO) items when bulk weighing occurs, maintains a detailed audit trail through ShipmentChosenProductWeighing records, and generates official PDF receipts known as "Nota Timbangan" for every weighing event.
Sources: CLAUDE.md, src/services/shipmentService.ts:1345-1355, src/services/notaTimbanganPdfService.ts
System Architecture & Workflows
The weighing system operates through three primary methods: Manual, Vendor, and Bulk. These methods are defined by the WEIGHING_METHOD enum and dictate how the system processes input weights and generates documentation.
Weighing Methods
| Method | Description | User Role |
|---|---|---|
| MANUAL | Internal staff manually enters gross, tare, and net weights via the shipment interface. | Internal Staff |
| VENDOR | Third-party systems submit weight data through a public API using a specialized x-auth key. | External Vendor |
| BULK | A single weight measurement is applied to multiple shipment items containing the same product. | Both |
Sources: src/schemas/shipment.ts:10-14, src/routes/vendorRoute.ts:10-25
Weighing Process Flow
The following diagram illustrates the lifecycle of a shipment item through the weighing process:
The system ensures that weights are not just recorded but also distributed. When multiple items are weighed in a "Loading Group," the total weight is divided among them based on their requestedQuantity proportions.
Sources: src/services/shipmentService.ts:1345-1400, src/services/shipmentService.ts:1430-1450
Core Components
Data Structures
The system uses specific relational models to track weighing sessions. A ShipmentChosenProduct acts as a header for a specific product in a shipment, which can then have multiple ShipmentChosenProductWeighing entries (weighing sessions).
Nota Timbangan PDF Generation
The notaTimbanganPdfService generates a 240x320 receipt-style PDF. It calculates the Average Weight (Net Weight / Total Quantity) and includes vehicle plate numbers, product names, and reference codes.
Key Logic in PDF Service:
- Timezone Management: Adjusts timestamps for production VPS environments (Asia/Jakarta).
- Linked Item Calculation: Filters shipment items to ensure the "Jumlah" (Quantity) on the receipt matches the items specifically linked to that weighing session ID.
- Dynamic Formatting: Formats numbers using the
id-IDlocale (e.g., using commas for decimals and dots for thousands).
Sources: src/services/notaTimbanganPdfService.ts:80-150, src/services/notaTimbanganPdfService.ts:160-180
Vendor API Integration
The system exposes a specialized public-facing API for third-party weighing scales. Unlike standard endpoints, these use an x-auth header key for authentication.
Vendor Endpoints
- GET
/api/vendor/shipments/available-items: Retrieves shipments with items specifically marked forVENDORweighing that are currently inCHOSENstatus. - POST
/api/vendor/shipments/weigh: AcceptsgrossWeight,netWeight, andtareWeight. It requires aloadingGroupIdto identify which specific batch of items is being weighed together.
Sources: src/routes/vendorRoute.ts:35-50, src/routes/vendorRoute.ts:210-230, src/controllers/vendorController.ts:90-130
Weight Distribution Logic
When a bulk weight is submitted, the shipmentService performs the following proportional calculation:
// Example from shipmentService.ts:1435
const proportion = item.requestedQuantity / totalRequestedQuantity;
const itemGrossWeight = data.grossWeight * proportion;
// Update the item with its share of the weight
await tx.shipmentItem.update({
where: { id: item.id },
data: {
weightedQuantity: itemGrossWeight,
status: SHIPMENT_ITEM_STATUS.COMPLETED,
shipmentChosenProductWeighingId: weighing.id
}
});
Sources: src/services/shipmentService.ts:1434-1445
Post-Weighing Revisions
The system allows for corrections even after weighing is completed. This is handled by reviseDeliveryOrderAfterWeighing and reviseShipmentItemAfterWeighing.
Recalculation Rules
- Weight per Unit: When a quantity is revised, the system calculates the original
weightPerUnit(Original Gross Weight / Original Quantity). - Proportional Adjustment: The new gross weight is set as
New Quantity * weightPerUnit. - Document Regeneration: If weights or quantities change, the existing "Nota Timbangan" and "SPMB" (Loading Order) PDF files are deleted from the storage and regenerated with new ticket numbers and updated data.
Sources: src/services/deliveryOrderService.ts:650-700, src/services/deliveryOrderService.ts:725-750
API Reference
Internal Weighing Schema
| Parameter | Type | Required | Description |
|---|---|---|---|
shipmentId | UUID | Yes | The ID of the parent shipment. |
productId | UUID | Yes | The ID of the product being weighed. |
grossWeight | Number | Yes | Total weight including packaging/vehicle. |
netWeight | Number | No | Weight of the goods only. |
tareWeight | Number | No | Weight of the empty container/vehicle. |
Sources: src/schemas/shipment.ts:110-125, comprehensive-swagger-api.json
Summary
The Weighing & Scales module provides a robust framework for logistics accuracy. By linking shipment items to specific weighing sessions, the system ensures inventory integrity. The use of proportional weight distribution allows the system to handle bulk weighing operations while maintaining granular data for individual delivery orders. Automated PDF generation and vendor API support further streamline the outbound process from the warehouse to the customer.
Sources: src/services/shipmentService.ts:1400-1500, src/services/notaTimbanganPdfService.ts:200-215