Transfer Dispatch Notes

Overview

The Transfer Dispatch Notes module manages the shipping/dispatch phase of inter-location inventory transfers. A dispatch note records what items are physically being shipped from an origin location to a destination location, including cost detail calculated from current inventory WAC (Weighted Average Cost).

Each dispatch note tracks:

• Origin and destination locations
• Items being dispatched (products, quantities)
• Cost detail calculated from current inventory costs at dispatch time
• Receipt summary tracking what has been received at destination (updated via Goods Receipt events)
• Goods receipt status (PARTIAL or RECEIVED) derived from the receipt summary
• Document number auto-generated for reference
• Transport detail optional shipping/carrier information

Architecture

transfers-dispatch-note/
├── transfers-dispatch-note.module.ts                    # NestJS module
├── domain/
│   └── transfers-dispatch-note-repository.domain.ts     # Port interface
├── application/
│   ├── transfers-dispatch-note.service.ts               # Use cases + event handlers
│   └── events/
│       ├── on-create-transfer-dispatch-note.event.ts    # Emitted on create
│       └── on-update-transfer-dispatch-note.event.ts    # Emitted on update
├── infrastructure/
│   └── transfers-dispatch-note.repository.ts            # Kysely adapter
└── interfaces/
    ├── transfers-dispatch-note.controller.ts            # HTTP routes
    ├── dtos/
    │   ├── create-transfer-dispatch-note.dto.ts
    │   └── update-transfer-dispatch-note.dto.ts
    └── query/
        └── paginate-transfers-dispatch-note.query.ts

Layer Responsibilities

Layer	Responsibility
Domain	Repository interface (port) — no framework dependencies
Application	Business logic: cost calculation, document number generation, receipt summary management, event handling for Goods Receipt integration
Infrastructure	Kysely database queries implementing the domain port
Interfaces	HTTP controllers, DTOs, query objects

Domain Concepts

Transfer Dispatch Note Lifecycle

1. Draft — Created with item details; costs auto-calculated from inventory WAC
2. Active — Approved and dispatched; items are in transit
3. Receiving — Goods Receipt Notes (TGR) are being submitted against this dispatch note; receipt summary tracks partial deliveries
4. Fully Received — All dispatched quantities have been received at destination

Receipt Summary

The receipt summary is a JSON array tracking per-item receipt progress. It is initialized on create and updated automatically when Transfer Goods Receipt events fire:

• OnCreateTransferGoodsReceiptEvent — when a TGR is created with status APPROVED
• OnUpdateTransferGoodsReceiptEvent — when a TGR transitions to APPROVED status

When total received equals total ordered, transferGoodsReceiptStatus is set to RECEIVED.

Cost Detail

On create/update, the service:

1. Extracts items from the detail JSON
2. Groups items by location and product
3. Ensures inventory records exist for all items
4. Fetches current WAC costs from inventory
5. Calculates cost detail using updateCostsFromReservedStock

API Endpoints

Method	Path	Description
POST	/transfers-dispatch-note	Create a new dispatch note
GET	/transfers-dispatch-note	List dispatch notes (paginated)
GET	/transfers-dispatch-note/search	Search with filters (date ranges, status, locations)
GET	/transfers-dispatch-note/:id	Get dispatch note by ID
GET	/transfers-dispatch-note/:id/pdf	Download PDF document
GET	/transfers-dispatch-note/:id/print	Get HTML print view
PATCH	/transfers-dispatch-note/:id	Update dispatch note
DELETE	/transfers-dispatch-note/:id	Delete dispatch note

Search Filters

The GET /search endpoint supports:

• businessId — filter by business UUID
• status — filter by status
• originLocationId / destinationLocationId — filter by location
• createdAtFrom / createdAtTo — date range on creation date
• dispatchDateFrom / dispatchDateTo — date range on dispatch date
• search — free-text search on location names
• Standard pagination: page, size, orderBy, order

Event Integration

Events Emitted

Event	When
transferDispatchNote.create	After a dispatch note is created
transferDispatchNote.update	After a dispatch note is updated

Events Consumed

Event	Action
transferGoodsReceipt.create	Updates receipt summary when TGR is created with APPROVED status
transferGoodsReceipt.update	Updates receipt summary when TGR transitions to APPROVED status

Design Decisions

1. Receipt summary updated via events — Keeps the dispatch note and goods receipt modules loosely coupled. The dispatch note service listens to TGR events rather than being called directly.

2. Cost calculated at dispatch time — WAC is captured at the moment of dispatch, not at transfer request time, ensuring accurate cost tracking for the actual shipment.

3. Shared date-range utility — Repository uses buildDateRangeCondition from @/utils/date-range-filter.utils for consistent date filtering across all inventory modules.