# Comprehensive Shipment Module Implementation Checklist

## Overview
This document outlines all shipment-related functionality from the old central system that needs to be replicated in the new Laravel-based central system.

---

## 📦 **1. SHIPMENT MENU STRUCTURE**

### Main Menu Item
- [ ] Add "Shipment" menu item in sidebar/navigation
  - Icon: `fa-truck`
  - Route: `/shipment`
  - Position: After "Order Fulfillment" menu item

### Related Menu Items
- [ ] "Shipping" submenu (under separate menu item)
  - [ ] Import Shipping (`/import-shipping`)
  - [ ] Search Shipping (`/import-shipping/search`)

---

## 📋 **2. SHIPMENT INDEX PAGE** (`/shipment`)

### Layout Structure
- [ ] Two-column layout at top (6+6 columns)
- [ ] Full-width shipments list below

### Components

#### A. Order Tracking Section (Top Left)
- [ ] Panel with header "Order tracking:"
- [ ] Form fields:
  - [ ] Text input for order number
  - [ ] "Track Now" button (blue, icon: `fa-crosshairs`)
- [ ] Form action: POST to `/shipment/track`

#### B. Bulk Shipping Section (Top Right)
- [ ] Panel with header "Bulk shipping:"
- [ ] Form fields:
  - [ ] File upload input
  - [ ] Warehouse dropdown (using `ShipmentHelper::getBulkWarehouses()`)
  - [ ] "Ignore Items Status" checkbox
  - [ ] "Ship Now" button (green, icon: `fa-bolt`)
- [ ] Form action: POST to `/shipment/bulk`
- [ ] Form enctype: `multipart/form-data`

#### C. Latest Shipments List (Full Width)
- [ ] Panel with header "Latest Shipments"
- [ ] Table columns:
  - [ ] Order # / Shipment #
  - [ ] Customer (limited width)
  - [ ] Address (limited width)
  - [ ] Carrier
  - [ ] Method
  - [ ] Warehouse
  - [ ] Tracking #
  - [ ] Submitted (date)
  - [ ] Shipped (date)
  - [ ] Actions (Delete button)
- [ ] Pagination (50 items per page)
- [ ] Delete modal functionality
- [ ] Order by: shipment_id DESC

---

## 🔍 **3. TRACKING PAGE** (`/shipment/track`)

### Components
- [ ] Same Order Tracking section as index
- [ ] Same Bulk Shipping section as index
- [ ] Shipments list filtered by order number
- [ ] Table header shows: "Shipments for Order # [order_number]"
- [ ] Same table structure as index page
- [ ] Delete functionality for each shipment

---

## 🚢 **4. SHIP ORDER PAGE** (`/shipment/ship/{orderId}`)
*Already partially implemented, needs completion*

### Existing Components (Verify/Update)
- [x] Billing Address display
- [x] Shipping Address display
- [x] Shipping Method section (Warehouse, Carrier, Method, Package)
- [x] Order Items table with supplier selection
- [x] Shipment Details form
- [x] Best Carrier calculation

### Missing/Needs Update
- [ ] Dropship Order Items section
  - [ ] Separate table for dropship items
  - [ ] Tracking number input
  - [ ] Carrier selection
  - [ ] "Dropship Now" button
- [ ] Form submission to `/shipment/result`
- [ ] Shipping cost estimates modal
- [ ] Extra partslink column in items table

---

## 🎯 **5. CONTROLLER ACTIONS** 

### ShipmentController Methods
- [x] `index()` - List all shipments with pagination
- [x] `track()` - Track shipments by order number
- [x] `ship()` - Display ship order form
- [x] `getDelivery()` - AJAX endpoint for best carrier rates
- [ ] `result()` - Process shipment creation
- [ ] `bulk()` - Process bulk shipments from file
- [ ] `dropship()` - Process dropship orders
- [ ] `delete()` - Delete a shipment
- [ ] `resendMagentoTrackingEmail()` - Resend tracking email
- [x] `getShippingCostEstimate()` - Get shipping estimates (AJAX)
- [ ] `getTotalDimensions()` - Calculate package dimensions (AJAX)

---

## 📊 **6. MODELS & DATABASE**

### Required Models
- [ ] `Shipment` model
  - Fields: shipment_id, order_id, tracking_number, carrier, method, warehouse, date_submitted, date_shipped, etc.
- [ ] `OrderItemShipment` model (pivot table)
  - Links order items to shipments
- [ ] `ImportShipping` model
- [ ] `DropshipperTracking` model

### Database Tables
- [ ] `shipments` table
- [ ] `order_items_shipments` table
- [ ] `import_shipping` table
- [ ] `dropshipper_tracking` table

---

## 🔧 **7. SERVICES & HELPERS**

### ShipmentHelper Functions
- [ ] `getBulkWarehouses()` - Get warehouses for bulk shipping
- [ ] `getCarriers()` - Get available carriers
- [ ] `getMethods()` - Get shipping methods
- [ ] `getPackageTypes()` - Get package types
- [ ] `getShippingCostEstimateHtml()` - Generate estimates HTML
- [ ] `processShipment()` - Process shipment creation

### ShipStationService (Already exists, verify)
- [x] `getRates()` - Get shipping rates from API
- [x] `createLabel()` - Create shipping label
- [ ] `voidLabel()` - Void a shipping label
- [ ] `getTracking()` - Get tracking information

### BulkShipmentHelper
- [ ] `processBulkFile()` - Process uploaded CSV/Excel file
- [ ] `validateBulkData()` - Validate bulk shipment data
- [ ] `createBulkShipments()` - Create multiple shipments

---

## 🎨 **8. VIEWS TO CREATE/UPDATE**

### Index View (`/resources/views/shipment/index.blade.php`)
- [ ] Create view with tracking, bulk upload, and shipments list
- [ ] Add pagination component
- [ ] Add delete modal

### Track View (`/resources/views/shipment/track.blade.php`)
- [ ] Create view with filtered shipments list
- [ ] Reuse components from index view

### Ship View (`/resources/views/shipment/ship.blade.php`)
- [x] Basic structure exists
- [ ] Add dropship section
- [ ] Add result processing
- [ ] Add validation

### Bulk Result View (`/resources/views/shipment/bulk-result.blade.php`)
- [ ] Create view to show bulk processing results
- [ ] Show success/error counts
- [ ] List of created shipments

---

## 🛣️ **9. ROUTES**

### Web Routes (Add to `/routes/web.php`)
```php
Route::middleware(['auth'])->group(function () {
    // Main shipment routes
    Route::get('/shipment', [ShipmentController::class, 'index'])->name('shipment.index');
    Route::match(['get', 'post'], '/shipment/track', [ShipmentController::class, 'track'])->name('shipment.track');
    Route::get('/shipment/ship/{orderId}', [ShipmentController::class, 'ship'])->name('shipment.ship');
    Route::post('/shipment/result', [ShipmentController::class, 'result'])->name('shipment.result');
    Route::post('/shipment/bulk', [ShipmentController::class, 'bulk'])->name('shipment.bulk');
    Route::post('/shipment/dropship', [ShipmentController::class, 'dropship'])->name('shipment.dropship');
    Route::delete('/shipment/delete/{id}', [ShipmentController::class, 'delete'])->name('shipment.delete');
    
    // AJAX endpoints
    Route::post('/shipment/get-delivery', [ShipmentController::class, 'getDelivery'])->name('shipment.getDelivery');
    Route::post('/shipment/get-shipping-cost-estimate', [ShipmentController::class, 'getShippingCostEstimate'])->name('shipment.getShippingCostEstimate');
    Route::post('/shipment/get-total-dimensions', [ShipmentController::class, 'getTotalDimensions'])->name('shipment.getTotalDimensions');
    
    // Email resend
    Route::post('/shipment/resend-tracking-email/{orderIncrementId}', [ShipmentController::class, 'resendMagentoTrackingEmail'])->name('shipment.resendTrackingEmail');
});
```

---

## ⚙️ **10. JAVASCRIPT FUNCTIONALITY**

### Ship Page JavaScript
- [x] Warehouse change handler
- [x] Carrier/Method filtering
- [x] Best carrier rate calculation
- [x] Shipping estimates modal
- [ ] Dropship form handling
- [ ] Package dimension auto-calculation
- [ ] Form validation

### Index/Track Page JavaScript
- [ ] Delete shipment modal
- [ ] Confirmation dialogs
- [ ] Bulk file validation
- [ ] AJAX status updates

---

## 🔐 **11. VALIDATION & SECURITY**

### Form Validation
- [ ] Order ID validation in ship action
- [ ] File type/size validation for bulk upload
- [ ] Required fields validation
- [ ] CSRF protection on all forms

### Permissions
- [ ] Check user permissions for shipment actions
- [ ] Admin-only features (bulk shipping)
- [ ] Warehouse-specific restrictions

---

## 📧 **12. INTEGRATIONS**

### ShipStation Integration
- [x] API credentials configuration
- [x] Rate calculation
- [ ] Label creation
- [ ] Tracking updates
- [ ] Webhook handling

### Magento Integration
- [ ] Send tracking information
- [ ] Update order status
- [ ] Send tracking emails

### Amazon MCF Integration
- [ ] Check FBA inventory
- [ ] Create fulfillment orders
- [ ] Get tracking information

---

## 🧪 **13. TESTING REQUIREMENTS**

### Unit Tests
- [ ] ShipmentController test
- [ ] ShipmentHelper test
- [ ] ShipStationService test
- [ ] Model tests

### Feature Tests
- [ ] Create shipment flow
- [ ] Bulk upload processing
- [ ] Tracking page functionality
- [ ] Delete shipment

### Integration Tests
- [ ] ShipStation API calls
- [ ] Database transactions
- [ ] Email sending

---

## 📦 **14. MIGRATION TASKS**

### Database Migrations
- [ ] Create shipments table migration
- [ ] Create order_items_shipments table migration
- [ ] Create import_shipping table migration
- [ ] Add indexes for performance

### Data Migration
- [ ] Migrate existing shipments data
- [ ] Migrate tracking numbers
- [ ] Update foreign key relationships

---

## 🚀 **15. DEPLOYMENT CHECKLIST**

### Pre-deployment
- [ ] All routes tested
- [ ] Database migrations ready
- [ ] API credentials configured
- [ ] File upload permissions set

### Post-deployment
- [ ] Verify menu items appear
- [ ] Test shipment creation
- [ ] Test bulk upload
- [ ] Verify tracking updates
- [ ] Check email notifications

---

## 📝 **IMPLEMENTATION PRIORITY**

### Phase 1 - Core Functionality (High Priority)
1. Shipment index page with listings
2. Basic ship order completion
3. Shipment result processing
4. Delete shipment functionality

### Phase 2 - Tracking & Search (Medium Priority)
1. Track shipments by order
2. Search functionality
3. Tracking email resend

### Phase 3 - Bulk Operations (Medium Priority)
1. Bulk shipment upload
2. Bulk processing
3. Dropship functionality

### Phase 4 - Advanced Features (Low Priority)
1. Import shipping
2. Advanced reporting
3. Webhook handling

---

## 📊 **PROGRESS TRACKING**

- **Total Tasks**: ~100+
- **Completed**: ~15
- **In Progress**: ~5
- **Remaining**: ~80

### Next Steps:
1. Create Shipment model and migration
2. Implement index page with listings
3. Complete ship order result processing
4. Add delete functionality
5. Implement tracking page

---

## 🔗 **RELATED DOCUMENTATION**

- Old Central Code: `/home/opstest/public_html/central/`
- New Central Code: `/home/opstest/public_html/central-new/`
- ShipStation API Docs: [ShipStation Developer Guide](https://www.shipstation.com/developer-api/)
- Laravel Docs: [Laravel 10.x Documentation](https://laravel.com/docs/10.x)

---

*Last Updated: 2025-08-21*
*This checklist should be updated as tasks are completed.*