Product Catalog & UoM

Relevant source files

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

• prisma/schema.prisma
• src/services/productService.ts
• src/controllers/warehouseController.ts
• comprehensive-swagger-api.json
• src/services/warehouseService.ts
• prisma/seed.ts

The Product Catalog & Unit of Measurement (UoM) module serves as the central repository for all items managed within the outbound logistics system. It defines the structural relationship between physical products, their designated storage locations (warehouses), and the specific units (satuan) used for tracking quantities and weights during shipment processes.

This module is critical for ensuring data consistency across Delivery Orders and Shipment Weighing operations. By enforcing strict associations between products and warehouses, the system prevents cross-facility inventory errors and provides a detailed audit trail for every catalog modification.
Sources: comprehensive-swagger-api.json, CLAUDE.md:25-30

Data Architecture

The architecture relies on a hierarchical relationship where products are scoped to specific warehouses. This ensures that inventory management is facility-specific while maintaining a unified catalog structure.

Entity Relationships

The following diagram illustrates the relationship between the Product entity and its primary associations:

The Product model includes a satuan field (Unit of Measurement) which is a mandatory string used to define how the product is quantified (e.g., "KG", "PCS").
Sources: prisma/schema.prisma:115-131, src/services/productService.ts:75-82

Product Data Model

Field	Type	Description	Constraints
id	UUID	Unique identifier for the product	Primary Key
name	String	Commercial name of the product	Required
id_sl	String	Legacy system identifier	Unique, Optional
description	String	Detailed information about the product	Optional
satuan	String	Unit of Measurement (UoM)	Required
warehouseId	UUID	Reference to the storage facility	Foreign Key
Sources: prisma/schema.prisma:115-131, comprehensive-swagger-api.json

Core Service Logic

The productService.ts handles the business logic for catalog management, including Jakarta timezone handling for timestamps and transactional integrity for audit logging.

Creation & Update Flow

When a product is created or updated, the system captures the performer's ID and logs the specific changes to maintain a historical record.

Timestamps are manually adjusted to Asia/Jakarta (UTC+7) within the service layer before persistence.
Sources: src/services/productService.ts:68-73, src/services/productService.ts:115-117

Implementation Example: Product Creation

async createProduct(data: ProductCreateInput, performedById: string) {
  const { warehouseId, ...productData } = data;

  return prisma.$transaction(async (tx) => {
    const jakartaTime = new Date();
    jakartaTime.setHours(jakartaTime.getHours() + 7);

    const product = await tx.product.create({
      data: {
        ...productData,
        createdAt: jakartaTime,
        updatedAt: jakartaTime,
        warehouse: { connect: { id: warehouseId } },
      },
      include: { warehouse: true },
    });
    // ... logging logic ...
    return product;
  });
}

Sources: src/services/productService.ts:65-102

Warehouse-Product Integration

Products are strictly coupled with warehouses. The warehouseService.ts provides specialized methods to manage these associations and retrieve facility-specific catalogs.

Warehouse Filtering Logic

The system allows retrieving products filtered by warehouseId with support for pagination and keyword searching across product names and legacy IDs (id_sl).

Endpoint	Method	Purpose
/api/warehouses/{id}/products	GET	Retrieve all products stored in a specific warehouse
/api/products	GET	Global search across all products with optional warehouse filter
Sources: src/controllers/warehouseController.ts:80-130, comprehensive-swagger-api.json

Unit of Measurement (UoM) Usage

The satuan field is utilized throughout the shipment and reporting lifecycles to ensure accurate weight calculations and volume summaries.

UoM in Weighing & Reports

1. Shipment Weighing: The UoM is displayed on PDF documents like the Nota Timbangan to clarify the weight units (typically 'kg').
2. Operational Reports: The reportService.ts aggregates shipment data by satuan to provide summary metrics.
3. SPMB Generation: The Surat Perintah Muat Barang (SPMB) includes the product quantity and name, derived directly from the catalog.

Audit & Lifecycle Management

Product lifecycle changes (creation, modification, and deletion) are captured by the ProductLog entity.

Deletion Policy

The system performs a hard delete for products but implements a specific cleanup procedure to maintain database integrity:

1. A deletion log is created containing the final state of the product (name, SKU, warehouse).
2. Existing logs for that product are disconnected (the productId reference is set to null) to prevent foreign key violations while preserving the history.
3. The product record is removed from the database.
   Sources: src/services/productService.ts:185-215, prisma/schema.prisma:133-148

Security & Permissions

Access to the Product Catalog is governed by Role-Based Access Control (RBAC). Standard permissions include:

• product:CREATE: Ability to add new items.
• product:READ: Ability to view the catalog.
• product:UPDATE: Ability to modify existing item details.
• product:DELETE: Ability to remove items from the catalog.
  Sources: prisma/seed.ts:140-155

Conclusion

The Product Catalog & UoM system provides the foundational data layer for the entire outbound logistics platform. By integrating strict warehouse associations, manual timezone synchronization, and a robust audit logging mechanism, the system ensures that every item moving through the supply chain is accurately tracked from storage to final delivery.