Module Planning: Shipment & Logistics

Overview

The Shipment Module handles the movement of products from stores to customers. It tracks the status of deliveries, manages courier information, and provides updates to both sellers and buyers.

Data Models

`Shipment`

Tracks an individual delivery process.

id (Primary Key)
hashkey (String, Unique)
transaction_id (Foreign Key to global_transactions or pos_transactions)
store_id (Foreign Key to stores)
customer_id (Foreign Key to cst)
courier_id (Foreign Key to couriers, nullable)
tracking_number (String, Unique)
status (Enum: PENDING, PICKED_UP, IN_TRANSIT, DELIVERED, FAILED, RETURNED)
origin_address (Text)
destination_address (Text)
estimated_delivery_date (DateTime)
actual_delivery_date (DateTime)
shipping_fee (Decimal)
created_by (Foreign Key to users)
updated_by (Foreign Key to users)
is_active (Boolean)

`Courier`

External or internal delivery services.

id (Primary Key)
hashkey (String, Unique)
name (String, e.g., "J&T Express", "Lalamove", "Local Rider")
contact_number (String)
type (Enum: EXTERNAL, INTERNAL)
is_active (Boolean)

Core Workflows

Shipment Creation: Triggered when an order is confirmed or a "Create Shipment" action is performed in the POS.
Courier Assignment: Assigning a courier to a pending shipment.
Status Updates: Manual or API-based updates as the package moves.
Delivery Confirmation: Final status update and timestamp recording.

API Endpoints (Proposed)

Endpoint	Method	Description
`/api/shipments`	GET	List all shipments (filtered by store/user)
`/api/shipments`	POST	Create a new shipment
`/api/shipments/{hashkey}`	GET	Get shipment details
`/api/shipments/{hashkey}/status`	PATCH	Update shipment status
`/api/couriers`	GET	List active couriers

UI Components (Vue)

ShipmentList.vue: Dashboard for tracking multiple deliveries.
ShipmentDetail.vue: detailed view of a single shipment with timeline.
CreateShipmentModal.vue: Form to initialize a shipment for an order.

2.2 KiB Raw Blame History