🚗 Vehicle Listing System

1. System Overview

The Vehicle Listing System allows verified dealers to manage their profiles and add vehicle listings. All listings go through an admin approval process before being visible to the public.

2. Dealer Profile Management

Dealers can manage their profile information including company details, location, and contact information.

Step-by-Step Guide

1. Login to Dealer Dashboard
   Navigate to: GET/dealers/login
   • Only verified dealers (status = ACTIVE) can access the dashboard
   • Dealers with PENDING status will see approval message
2. Access Profile
   Go to: GET/dealers/profile
   • View current dealer information
   • Navigate to different profile sections (Account, Company, Representative, Financial, Business, Documents)
   • Separate dealer layout and navigation
3. Update Account Information
   Routes:
   • POST/dealers/profile - Edit form
   • PUT/dealers/profile - Update account data

   Fields: First Name, Last Name, Phone, Gender, Date of Birth

4. Update Company Information
   Routes:
   • POST/dealers/profile/company - Edit form
   • PUT/dealers/profile/company - Update data

   Fields: Company Name, Registration Number, Tax ID, Address (Country, State, City, Street, Postal Code)

5. Manage Authorized Representative Information
   Routes:
   • POST/dealers/profile/representative/create - Show add form
   • POST/dealers/profile/representative - Store new representative
   • POST/dealers/profile/representative/{id} - Edit form
   • PUT/dealers/profile/representative/{id} - Update data

   Fields: Full Name*, NIC/Passport, Position, Contact Phone, Contact Email

   Layout: Table view with add/edit functionality

6. Manage Bank & Financial Information
   Routes:
   • POST/dealers/profile/financial/create - Show add form
   • POST/dealers/profile/financial - Store new financial info
   • POST/dealers/profile/financial/{id} - Edit form
   • PUT/dealers/profile/financial/{id} - Update data

   Fields: Bank Name*, Account Holder Name*, Account Number*

   Layout: Table view with add/edit functionality

7. Update Business Information
   Routes:
   • POST/dealers/profile/business - Edit form
   • PUT/dealers/profile/business - Update data

   Fields: Operations, Branches, Website

8. Manage Documents
   Routes:
   • POST/dealers/profile/documents - Edit form
   • PUT/dealers/profile/documents - Update/Upload documents
9. Update Avatar
   Routes:
   • POST/dealers/profile/avatar - Edit form
   • PUT/dealers/profile/avatar - Update avatar
10. Change Password
    Routes:
    • POST/dealers/profile/password - Edit form
    • PUT/dealers/profile/password - Update password
11. View Terms
    Route: GET/dealers/profile/terms
12. Update Settings
    Route: POST/dealers/settings
    • Dark mode toggle
    • Compact sidebar toggle

3. Add Vehicle Listing - Complete Feature

Step-by-Step Guide

1. Navigate to Listings
   From Dealer Dashboard, go to: GET/dealers/listings
2. Create New Listing
   Click "Add New Listing" → GET/dealers/listings/create
3. Fill Required Fields

   Field	Description	Validation
   VIN	Vehicle Identification Number	Required, exactly 17 characters, unique
   Make	Manufacturer (e.g., Honda, Toyota)	Required, max 255 characters
   Model	Vehicle model name	Required, max 255 characters
   Year	Manufacturing year	Required, integer (1900 to current year + 1)
   Trim	Edition/variant	Optional, max 255 characters
   Mileage	Vehicle mileage	Required, integer, min 0
   Price	Listing price	Required, numeric, min 0
   Condition	Vehicle condition	Required, select from: New, Used, Certified Pre-Owned
   Exterior Color	Vehicle exterior color	Required, max 255 characters
   Interior Color	Vehicle interior color	Required, max 255 characters
   Car Photos	Multiple vehicle images	Required, minimum 3 images, max 5MB each
   Description	Vehicle description	Optional, text field

4. Upload Images
   Use: POST/dealers/listings/upload-image
   • Drag and drop or click to upload
   • Supported formats: JPEG, JPG, PNG, GIF, WEBP
   • Maximum file size: 5MB per image
   • Minimum 3 images required
5. Submit Listing
   Route: POST/dealers/listings
   • Listing is created with Status: PENDING
   • Admin receives notification for approval
   • Dealer sees confirmation message

Listing Workflow

4. Admin Approval Process

For Listings

1. View Pending Listings
   Admin Dashboard → Listings → GET/admin/listings
2. Review Listing Details
   Click on listing → GET/admin/listings/{uuid}
   • View all vehicle specifications
   • Check images
   • Review dealer information
3. Approve Listing
   Route: POST/admin/listings/{id}/approve
   • Changes status from PENDING → APPROVED
   • Listing becomes visible on public platform
   • Dealer receives notification
4. Reject Listing
   Route: POST/admin/listings/{id}/reject
   • Changes status from PENDING → SUSPENDED
   • Listing is hidden from public platform
   • Dealer receives notification

For Dealers

1. View Pending Dealers
   Admin Dashboard → Dealers → GET/admin/dealers
2. Verify Email (Optional)
   Route: POST/admin/dealers/verify-email/{uuid}
   • Changes user status to VERIFIED
3. Approve Dealer
   Route: POST/admin/dealers/approve/{uuid}
   • Sets user status to ACTIVE
   • Sets verified_at timestamp
   • Dealer can now login and access dashboard
4. Reject Dealer
   Route: POST/admin/dealers/reject/{uuid}
   • Sets user status to SUSPENDED
   • Dealer cannot access dashboard

5. Data Flow & Database Structure

Complete Data Flow Diagram

Database Tables Structure

Key Relationships

6. API Routes Reference

Dealer Routes (Protected: auth, verified, verified_dealer)

Admin Routes (Protected: auth, active)

Dealer Profile Management Routes (Protected: auth, verified, verified_dealer)

7. Status Flow & Enums

User Status Enum

Listing Status Flow

8. Implementation Timeline

9. Quick Start Guide

For Dealers

1. Register: Go to /dealers-register
2. Wait for Approval: Admin will approve your account
3. Login: Use /dealers/login with your credentials
4. Access Dashboard: After login, you'll be redirected to /dealers/dashboard
5. Update Profile: Click on "Profile" in navigation → /dealers/profile
6. Manage Representatives: Add/Edit authorized representatives with table view
7. Manage Financial Info: Add/Edit bank account information with table view
8. Add Listings: Go to Listings → Add New
9. Wait for Approval: Admin reviews and approves listings

For Admins

1. Review Dealers: Admin Dashboard → Dealers
2. Approve Dealers: Click approve button on pending dealers
3. Review Listings: Admin Dashboard → Listings
4. Approve/Reject: Click approve or reject on pending listings
5. Manage Platform: All approved listings appear on public platform