initial: bootstrap from BukidBountyApp base

ai-docs/modules/shipment_module.md

@@ -0,0 +1,56 @@
+# 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.