SPMB Document Service
Relevant source files
The following files were used as context for generating this wiki page:
The SPMB Document Service (Surat Perintah Muat Barang) is a critical component of the Outmanage logistics system responsible for generating, managing, and maintaining official loading instruction documents. These documents serve as formal authorizations for warehouse staff to load specific products from designated warehouses onto assigned vehicles for delivery or pickup.
The service integrates tightly with the Shipment Service and Delivery Order Service to ensure that every logistics movement is backed by a verifiable PDF document. Each SPMB is uniquely identified by a code—often prefixed by warehouse identifiers—and contains detailed information regarding the customer, vehicle, driver, and the specific items to be moved.
Sources: src/services/spmbPdfService.ts:80-90, CLAUDE.md:45-50
Architecture and Data Flow
The SPMB system follows a structured lifecycle triggered by shipment creation or modification. When shipment items are grouped by their respective delivery orders and source warehouses, the system generates distinct SPMB records.
Document Lifecycle
- Generation Trigger: SPMBs are created during initial shipment creation or when a shipment is updated with new items.
- PDF Rendering: The system uses
PDFKitto generate a landscape A5 document. - Storage: Generated PDFs are stored in a dedicated directory (
/public/spmb/) and their relative paths are saved in the database. - Regeneration: Critical changes such as customer reassignments, item quantity revisions, or tally updates trigger the deletion of old files and the creation of new documents to maintain data integrity.
The diagram above illustrates the automated flow from business events to physical document storage.
Sources: src/services/spmbPdfService.ts:15-30, src/services/shipmentService.ts:550-600, src/services/deliveryOrderService.ts:1000-1050
PDF Generation Logic
The document generation logic is encapsulated in the spmbPdfService. It produces an A5 landscape document with specific metadata and item tables.
Document Layout
- Header: Displays "SPMB" and "(Surat Perintah Muat Barang)".
- Metadata Sections:
- Left Side: SPMB Number, Date, and Customer Name.
- Right Side: Plate Number, Driver Name, Tally, and Internal Notes.
- Item Table: A two-column table showing Quantity and Item Name.
- Special Formatting: Items with a
CANCELLEDstatus are rendered with a strikethrough effect. - Signature Area: A "Dibuat Oleh" (Created By) section aligned at the bottom right.
Sources: src/services/spmbPdfService.ts:85-160
Data Structures
The generation process requires complex joins across several entities:
| Field | Source Entity | Description |
|---|---|---|
code | SPMB | Unique identifier (e.g., WH-XXXXXX) |
plateNumber | Shipment / Armada | Vehicle identification |
customer.name | Delivery Order | Recipient of the goods |
requestedQuantity | Shipment Item | Total units to be loaded |
product.name | Product | Name of the goods |
Sources: src/services/spmbPdfService.ts:40-75
SPMB Management and Schemas
Data integrity is enforced through Joi validation schemas and database constraints.
Validation Rules
The createSPMBSchema ensures that every document is linked to a valid shipment, delivery order, and warehouse using UUID formats.
export const createSPMBSchema = Joi.object<SPMBCreateInput>({
shipmentId: Joi.string().required().uuid(),
deliveryOrderId: Joi.string().required().uuid(),
warehouseId: Joi.string().required().uuid(),
code: Joi.string().required().max(50),
documentPath: Joi.string().allow('', null).max(500),
generatedById: Joi.string().uuid().optional(),
});
Sources: src/schemas/spmb.ts:20-40
Database Interaction
SPMBs are managed via Prisma transactions to ensure that file system changes (deleting old PDFs) and database updates (clearing paths or updating codes) happen atomically or revert on failure.
| Operation | Implementation Detail |
|---|---|
| Creation | Grouped by deliveryOrderId and warehouseId during shipment setup. |
| Deletion | Soft deletion of shipments triggers physical deletion of SPMB PDF files. |
| Regeneration | Triggered by reviseShipmentItemAfterWeighing or changeCustomerAfterWeighing. |
Sources: src/services/shipmentService.ts:1300-1350, src/services/deliveryOrderService.ts:1450-1500
Integration with Logistics Workflow
The SPMB Document Service is deeply integrated into the weighing and revision workflows.
Revision Handling
When a delivery order is revised after weighing, the system automatically:
- Identifies all existing SPMBs associated with the DO.
- Deletes the physical PDF files from storage.
- Generates new codes using
customAlphabet(e.g.,SPMB-XXXXXX). - Rerenders the PDFs with updated quantities.
Sources: src/services/deliveryOrderService.ts:1150-1200
Warehouse-Specific Grouping
A single shipment may contain items from multiple warehouses. The service ensures that a separate SPMB is generated for each warehouse so that warehouse-specific staff only see the items relevant to their location.
Conclusion
The SPMB Document Service provides the necessary legal and operational documentation required for physical goods movement. By automating the generation and regeneration of these documents based on real-time database changes, it ensures that warehouse operations are always synchronized with the latest shipment data, vehicle assignments, and customer requirements. This automation significantly reduces manual errors in loading instructions and provides a reliable audit trail for every item dispatched from the facility.