# 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

1. **Shipment Creation**: Triggered when an order is confirmed or a "Create Shipment" action is performed in the POS.
2. **Courier Assignment**: Assigning a courier to a pending shipment.
3. **Status Updates**: Manual or API-based updates as the package moves.
4. **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.