# Quick Start Guide - Shopping Cart & Checkout

## 🚀 Getting Started

### Prerequisites
- PHP 8.2+
- MySQL/MariaDB
- Node.js & npm
- Laravel 12
- Jetstream with Inertia

### Installation & Setup

```bash
# 1. Install dependencies
composer install
npm install

# 2. Create .env file
cp .env.example .env

# 3. Generate app key
php artisan key:generate

# 4. Create database and run migrations
php artisan migrate

# 5. Create storage link for images
php artisan storage:link

# 6. Build frontend assets
npm run dev   # For development
npm run build # For production

# 7. Start the development server
php artisan serve
```

## 📋 User Registration

### Three User Roles Available
1. **Customer** - Can browse vehicles, add to cart, checkout, track orders
2. **Seller** - Can list vehicles, manage inventory, track orders
3. **Admin** - Can manage all users, orders, vehicles, and view analytics

Register with role selection during signup.

## 🛒 Customer Workflow

### 1. Browse Vehicles
- Navigate to home page `/`
- View all available vehicles
- Use search/filter to find specific vehicles
- Check vehicle details, price, condition, mileage

### 2. Add to Cart
- On vehicle detail page, click "Add to Cart" button
- Vehicle added to shopping cart
- Confirm with "View Cart" or continue shopping

### 3. View Shopping Cart
- Go to `/customer/cart`
- See all items in cart with:
  - Vehicle images and details
  - Current quantity
  - Unit price
  - Discount (if applicable)
  - Total for each item
  - Order summary with totals

### 4. Manage Cart
- **Increase Quantity**: Click `+` button
- **Decrease Quantity**: Click `−` button
- **Remove Item**: Click "Remove" link
- **Clear Cart**: Click "Clear Cart" button
- **Continue Shopping**: Click "Continue Shopping" button

### 5. Checkout
- Click "Proceed to Checkout" button
- Enter shipping address in textarea
- Select payment method:
  - Credit/Debit Card
  - Bank Transfer
  - Cash on Delivery
- Add optional order notes
- Click "Place Order" button

### 6. Order Confirmation
- Redirected to order detail page
- See complete order summary
- View order items, shipping address, payment info
- Track order status

### 7. Order Tracking
- Visit `/customer/orders`
- See list of all your orders with status and total
- Click order to view full details
- Track shipping with tracking number (when available)
- View payment status
- See order timeline (order date, shipped date, delivered date)

## 🚚 Seller Dashboard

### Navigate to Seller Section
- Login as seller
- Click "Dashboard" in navigation
- Access `/seller/dashboard`

### Seller Dashboard Shows
- Total vehicles listed
- Available vehicles count
- Total orders received
- Pending orders needing attention
- Total revenue from completed sales
- Recent vehicles listed
- Quick action buttons

### Manage Orders
1. Click "View Orders" button or go to `/seller/orders`
2. See table of all orders for your vehicles with:
   - Order ID and customer name
   - Number of items
   - Order total
   - Current status
   - Order date
3. Click "View" to open order details
4. Update order status:
   - pending → paid → shipped → delivered
   - Or cancel order
5. Add tracking number when shipping
6. See customer information
7. View payment status

## 👨‍💼 Admin Dashboard

### Admin Overview
- Access `/admin/dashboard`
- View system-wide metrics:
  - Total sellers
  - Total vehicles
  - Available vehicles
  - Sold vehicles
  - Featured listings
  - Clearance listings
  - Top vehicle types

### Admin Orders Management
1. Go to `/admin/orders`
2. See 6 stat cards:
   - Total Orders
   - Pending Orders
   - Paid Orders
   - Shipped Orders
   - Delivered Orders
   - Total Revenue
3. Browse all orders in system table
4. Click order to view/edit details
5. Update any order status
6. Add tracking numbers
7. View payment information

## 🔄 Order Status Meanings

- **Pending**: Order received, awaiting payment/confirmation
- **Paid**: Payment processed, order confirmed
- **Shipped**: Order dispatched to customer
- **Delivered**: Customer received order
- **Cancelled**: Order cancelled by seller or customer

## 💳 Payment Methods

Orders support 3 payment methods:
1. **Credit/Debit Card** - For online card payments
2. **Bank Transfer** - For direct bank transactions
3. **Cash on Delivery** - Payment upon delivery

*(Additional integrations like Stripe, PayPal can be added)*

## 📊 Discount System

- Vehicles can have discount percentages
- Discount automatically calculated in cart
- Discount shows in order summary
- Final price = (Unit Price - Discount) × Quantity

## 🎯 Key Features

### Shopping Cart
- ✅ Add multiple vehicles with quantities
- ✅ View detailed order summary
- ✅ Adjust quantities easily
- ✅ Remove individual items
- ✅ Apply automatic discounts
- ✅ See real-time totals

### Checkout
- ✅ Simple multi-step form
- ✅ Shipping address entry
- ✅ Payment method selection
- ✅ Order notes/special instructions
- ✅ Final review before placing order
- ✅ Order confirmation

### Order Tracking
- ✅ Full order history
- ✅ Order status visualization
- ✅ Tracking numbers
- ✅ Timeline view
- ✅ Payment status
- ✅ Customer support reference

### Seller Management
- ✅ See all orders for your vehicles
- ✅ Update order status
- ✅ Add tracking information
- ✅ View customer details
- ✅ Dashboard analytics
- ✅ Revenue tracking

### Admin Control
- ✅ System-wide order management
- ✅ Update any order status
- ✅ View all customer activity
- ✅ Revenue analytics
- ✅ Order pipeline tracking
- ✅ User management

## 🔐 Security Features

- Role-based access control
- Authorization policies on cart items
- Seller sees only their orders
- Customers see only their orders
- Admin access controlled via middleware
- CSRF protection on all forms

## 🐛 Troubleshooting

### Cart not saving items
- Ensure you're logged in as customer role
- Check browser console for JavaScript errors
- Verify database connection

### Orders not appearing
- Check user role (must be customer to place orders)
- Verify database migrations ran successfully
- Check order status in admin panel

### Images not showing
- Run: `php artisan storage:link`
- Verify image files exist in storage/app/public
- Check file permissions

### Payment method not submitting
- Verify all form fields are filled
- Check browser console for validation errors
- Ensure customer is logged in

## 📞 Support

For issues or features:
1. Check IMPLEMENTATION_SUMMARY.md for detailed architecture
2. Review database migrations for schema
3. Check controller logic in app/Http/Controllers/
4. Review Vue component templates in resources/js/Pages/

## 📚 File Structure

```
Key Implementation Files:
├── app/Models/
│   ├── Order.php          (Updated with items relation)
│   ├── OrderItem.php      (NEW - Order items)
│   ├── Cart.php           (NEW - Shopping cart)
│   └── Payment.php        (Updated)
├── app/Http/Controllers/
│   ├── Customer/CartController.php        (NEW)
│   ├── Customer/CheckoutController.php    (NEW)
│   ├── Customer/OrderController.php       (Updated)
│   ├── Seller/OrderController.php         (NEW)
│   └── Admin/OrderController.php          (Updated)
├── resources/js/Pages/
│   ├── Customer/Cart/Index.vue            (NEW)
│   ├── Customer/Checkout/Index.vue        (NEW)
│   ├── Seller/Orders/                    (NEW)
│   └── Admin/Orders/                     (Updated)
└── database/migrations/
    ├── create_carts_table
    ├── create_order_items_table
    └── (and others)
```

Happy selling! 🎉